China Holiday MCP Server

Overview

The China Festival MCP Server is a specialized Model Context Protocol (MCP) service that equips AI assistants with authoritative, real‑time access to a comprehensive set of Chinese calendrical data. It resolves the common challenge developers face when building culturally aware applications: reliably determining whether a given date is a national holiday, a traditional festival, or a working day, and converting between Gregorian and lunar calendars. By exposing this data through MCP tools, the server eliminates the need for external APIs or manual lookup tables, streamlining integration into AI workflows such as scheduling assistants, travel planners, and educational bots.

What the Server Does

At its core, the server offers a suite of query tools that return richly structured JSON responses. Developers can ask for holiday status, next upcoming holiday, or the full list of holidays and workdays for a given year. It also provides lunar calendar conversions, detailed lunar descriptors (including zodiac signs and heavenly stems/earthly branches), the 24 solar terms, and even BaZi (Four Pillars) calculations for a birth date. Each tool is type‑checked and validated automatically, ensuring that AI assistants receive consistent, error‑free data without additional parsing logic.

Why It Matters

For developers building AI applications that need to be sensitive to Chinese cultural and regulatory contexts—such as scheduling systems, event planners, or educational platforms—the server removes a major friction point. Rather than embedding static holiday lists that quickly become outdated, the MCP service pulls from up‑to‑date datasets and presents them in a format that Claude or any other MCP‑compatible client can consume directly. This leads to fewer bugs, reduced maintenance overhead, and a more seamless user experience.

Key Features & Capabilities

• Holiday Query: Detect whether a date is a national holiday, traditional festival, or working day; includes notes on shift work.
• Lunar Conversion: Bidirectional conversion between Gregorian and lunar dates, with leap month handling.
• Lunar Details: Full Chinese date descriptors (year‑gan‑zhi, month name, day name) and zodiac information.
• Solar Terms: Access to the 24 solar terms, their dates, and seasonal context.
• BaZi Calculation: Compute the Four Pillars of a birth date/time for use in astrology or personalized content.
• FastMCP Architecture: Built on the official FastMCP framework, ensuring high performance and adherence to MCP best practices.

Real‑World Use Cases

• Smart Calendar Assistants: Automatically adjust meeting schedules based on upcoming holidays or workdays.
• Travel & Hospitality Bots: Offer travelers accurate holiday information to plan itineraries or avoid peak travel times.
• Educational Tools: Teach students about Chinese culture by providing instant explanations of festivals, lunar dates, and zodiac signs.
• HR & Payroll Systems: Calculate overtime or holiday pay accurately by querying the server for official workday status.

Integration with AI Workflows

Developers configure the MCP server once in their client (e.g., Claude Desktop) using a simple JSON snippet that points to the server’s executable. Afterward, any prompt can invoke the exposed tools—, , , etc.—and receive structured data instantly. The AI can then embed that information into responses, schedule logic, or downstream services without additional round‑trips to external APIs.

Unique Advantages

• Single Source of Truth: All holiday and calendrical data is centrally maintained, reducing duplication across applications.
• Zero‑Latency Data: The server runs locally (or on a private host), eliminating network delays inherent to public APIs.
• Extensibility: Built on FastMCP, developers can add new tools or data sources without refactoring the core protocol logic.
• Compliance & Localization: The server aligns with Chinese governmental holiday schedules and traditional calendar conventions, ensuring culturally accurate outputs.

In summary, the China Festival MCP Server is a robust, developer‑friendly solution that empowers AI assistants to deliver precise, culturally aware calendrical intelligence with minimal effort.