How do I use China Festival MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@China Festival MCP Server what are the upcoming Chinese holidays this year?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

中国节假日MCP服务器

一个基于模型上下文协议（MCP）的中国节假日和农历信息服务器，为AI助手提供准确的法定节假日、调休安排、中国传统节日、农历转换、二十四节气和八字计算功能。西方节日都是固定公历日期，不需要查询工具。

🌟 功能特性

节假日查询: 查询中国法定节假日、传统节日和调休安排
农历转换: 公历与农历日期相互转换
农历信息: 获取详细的农历日期描述，包括生肖、干支等
二十四节气: 查询二十四节气信息和季节划分
八字计算: 根据出生日期时间计算四柱八字和五行属性
FastMCP架构: 基于官方推荐的FastMCP框架，提供更好的性能和稳定性

🏗️ 技术架构

本项目基于官方推荐的FastMCP框架开发，具有以下特性：

简化的工具注册: 使用 @mcp.tool() 装饰器
自动类型验证: 自动处理参数验证和类型转换
标准化接口: 完全符合MCP协议最佳实践

📦 安装

环境要求

Python 3.8+
支持MCP协议的AI客户端（如Claude Desktop）

使用uvx安装（推荐）

# 直接从PyPI安装并运行
uvx china-festival-mcp

本地开发安装

# 克隆项目
git clone https://github.com/your-username/china-festival-mcp.git
cd china-festival-mcp

# 使用uvx运行（会自动安装依赖）
uvx --from . python -m src.server_fastmcp

🚀 使用方法

# 从PyPI直接运行
uvx china-festival-mcp

# 或本地开发运行
uvx --from . python -m src.server_fastmcp

⚙️ MCP客户端配置

Claude Desktop配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

从PyPI安装（推荐）

{
  "mcpServers": {
    "china-festival-mcp": {
      "command": "uvx",
      "args": ["china-festival-mcp"]
    }
  }
}

本地开发

{
  "mcpServers": {
    "china-festival-mcp": {
      "command": "uvx",
      "args": ["--from", ".", "python", "-m", "src.server_fastmcp"],
      "cwd": "/path/to/china-festival-mcp"
    }
  }
}

其他MCP客户端

对于其他支持MCP协议的客户端，使用相同的uvx配置方式：

{
  "mcpServers": {
    "china-festival-mcp": {
      "command": "uvx",
      "args": ["china-festival-mcp"]
    }
  }
}

📚 API文档

节假日工具

`holiday_info`

查询指定日期的节假日信息，包含是否为节假日的判断

返回:

{
  "date": "2024-01-01",
  "name": "元旦",
  "type": "holiday",
  "is_holiday": true,
  "is_work_day": false,
  "note": "法定节假日",
  "weekday_name_en": "Monday"
}

`next_holiday`

获取下一个节假日

返回:

{
  "name": "春节",
  "date": "2024-02-10",
  "days_until": 40,
  "note": "法定节假日",
  "weekday_name_en": "Saturday"
}

`current_year_holidays`

获取当前年份所有节假日

返回:

{
  "year": 2024,
  "holidays": [
    {
      "date": "2024-01-01",
      "name": "元旦",
      "note": "法定节假日"
    }
  ],
  "total_count": 1
}

`current_year_work_days`

获取当前年份调休工作日安排

返回:

{
  "year": 2024,
  "work_days": [
    {
      "date": "2024-02-04",
      "name": "春节调休",
      "note": "调休工作日"
    }
  ],
  "total_count": 1
}

农历工具

`gregorian_to_lunar`

公历转农历

返回:

{
  "gregorian_date": "2024-01-01",
  "lunar_year": 2023,
  "lunar_month": 11,
  "lunar_day": 20,
  "is_leap_month": false,
  "zodiac": "兔"
}

`lunar_to_gregorian`

农历转公历

返回:

{
  "lunar_date": "2023年十一月二十",
  "gregorian_year": 2024,
  "gregorian_month": 1,
  "gregorian_day": 1,
  "gregorian_date": "2024-01-01"
}

`get_lunar_string`

获取农历日期的详细中文描述

返回:

{
  "gregorian_date": "2024-01-01",
  "lunar_year": 2023,
  "lunar_month": 11,
  "lunar_day": 20,
  "is_leap_month": false,
  "zodiac": "兔",
  "year_gan_zhi": "癸卯",
  "tian_gan": "癸",
  "di_zhi": "卯",
  "lunar_month_name": "十一月",
  "lunar_day_name": "二十",
  "lunar_string": "癸卯年 十一月 二十"
}

`get_24_lunar_feast`

获取二十四节气信息

返回:

{
  "year": 2024,
  "month": 1,
  "solar_terms": [
    {
      "name": "小寒",
      "date": "2024-01-06",
      "days_until": 5,
      "season": "冬季"
    },
    {
      "name": "大寒",
      "date": "2024-01-20",
      "days_until": 19,
      "season": "冬季"
    }
  ]
}

`get_8zi`

计算八字（四柱）

返回:

{
  "eight_characters": "甲辰 丙寅 甲子 庚午"
}

日期工具

`get_weekday`

根据公历日期计算星期几

返回:

{
  "weekday_number": 1,
  "weekday_name_zh": "星期一",
  "weekday_name_en": "Monday",
  "date": "2024-01-01"
}

📁 项目结构

china-festival-mcp/
├── src/                       # 核心源代码
│   ├── __init__.py
│   ├── server_fastmcp.py      # FastMCP服务器主程序
│   ├── data/                  # 数据模块
│   │   ├── bazi_calculator.py # 八字计算模块
│   │   └── solar_terms.py     # 二十四节气数据
│   ├── tools/                 # 工具模块
│   │   ├── __init__.py
│   │   ├── holiday.py         # 节假日查询工具
│   │   ├── lunar.py           # 农历转换工具
│   │   └── weekday.py         # 星期计算工具
│   └── utils/                 # 工具函数
│       ├── __init__.py
│       ├── date_utils.py      # 日期工具
│       └── logger.py          # 日志管理
├── scripts/                   # 发布脚本
│   └── publish.py             # 自动发布脚本
├── test_solar_terms.py        # 节气测试脚本
├── .gitignore                 # Git忽略文件
├── pyproject.toml             # 项目配置和依赖
├── README.md                  # 项目说明
├── LICENSE                    # 许可证
├── PUBLISH_GUIDE.md           # 发布指南
└── publish.sh                 # 发布脚本

🙏 致谢

本项目基于 PyLunar 项目和 holiday-cn项目开发，感谢原作者的贡献。

China Festival MCP Server

中国节假日MCP服务器

🌟 功能特性

🏗️ 技术架构

📦 安装

环境要求

使用uvx安装（推荐）

本地开发安装

🚀 使用方法

⚙️ MCP客户端配置

Claude Desktop配置

从PyPI安装（推荐）

本地开发

其他MCP客户端

📚 API文档

节假日工具

`holiday_info`

`next_holiday`

`current_year_holidays`

`current_year_work_days`

农历工具

`gregorian_to_lunar`

`lunar_to_gregorian`

`get_lunar_string`

`get_24_lunar_feast`

`get_8zi`

日期工具

`get_weekday`

📁 项目结构

🙏 致谢

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API