China Festival

You have an MCP server that provides accurate Chinese statutory holidays, traditional festivals, lunar calendar conversions, solar terms, and eight-character (BaZi) calculations. It connects with MCP clients to deliver structured holiday data and calendar insight for AI assistants and workflows in China-focused contexts.

How to use

Connect your MCP client to the server to query holidays, convert between Gregorian and lunar calendars, fetch lunar details, and compute BaZi. You can call holiday-related tools to check official holidays and workdays, use lunar tools for calendar conversions, and leverage date utilities for weekday information.

How to install

Prerequisites: you need Python 3.8+ and a MCP client that supports the MCP protocol.

Install and run the MCP server from PyPI using the recommended tool:

Step-by-step install from PyPI and local development

# From PyPI
uvx china-festival-mcp

# Local development
# Clone the project
git clone https://github.com/your-username/china-festival-mcp.git
cd china-festival-mcp

# Run the server from the local checkout
uvx --from . python -m src.server_fastmcp

Configure your MCP client to connect to this server

If your client supports JSON configuration for MCP servers, you can add a local stdio server entry that points to the runtime command and arguments. The two valid runtime options shown below reflect running from PyPI and running from a local checkout.

{
  "mcpServers": {
    "china_festival_mcp_pypi": {
      "command": "uvx",
      "args": ["china-festival-mcp"]
    },
    "china_festival_mcp_dev": {
      "command": "uvx",
      "args": ["--from", ".", "python", "-m", "src.server_fastmcp"]
    }
  }
}

Additional configuration notes

Environment variables are not strictly required for basic usage. If you enable specific features or need to adapt to your environment, you can pass environment variables to the MCP client or server as needed.

API / available tools

You can access the following tools to retrieve and compute calendar and holiday data. Each tool returns structured JSON data suitable for integration into chat assistants and workflows.

Notes on data and capabilities

The server provides holiday queries for statutory holidays and traditional Chinese festivals, lunar calendar conversions, detailed lunar descriptions, the twenty-four solar terms, BaZi (eight-character) calculations, and weekday information. These capabilities are designed to support AI assistants that need accurate calendar data and cultural date calculations.

Troubleshooting

If the MCP client fails to connect, verify that the MCP server is reachable and that the command and arguments you configured match one of the runtime invocations shown above. Ensure your Python environment meets the minimum version requirement and that the client supports the MCP protocol.

Available tools

holiday_info

Query holiday information for a specific date, including whether it is a holiday, whether it is a workday, and related notes.

next_holiday

Retrieve the next upcoming holiday with its date, name, and days until occurrence.

current_year_holidays

List all holidays for the current year along with counts.

current_year_work_days

List all compensatory workdays for the current year along with counts.

gregorian_to_lunar

Convert a Gregorian date to its corresponding lunar date and related fields.

lunar_to_gregorian

Convert a lunar date to its corresponding Gregorian date.

get_lunar_string

Get a detailed Chinese lunar description including year, month, day, zodiac, and cyclic stems/branches.

get_24_lunar_feast

Fetch information about the twenty-four solar terms for a given year.

get_8zi

Calculate the four pillars (BaZi) based on birth date and time.

get_weekday

Determine the weekday for a given Gregorian date.