中国节假日MCP服务器

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

🌟 功能特性

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

🏗️ 技术架构

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

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

📦 安装

环境要求

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

使用uvx安装（推荐）

bash

直接从PyPI安装并运行

uvx china-festival-mcp

本地开发安装

bash

克隆项目

git clone https://github.com/your-username/china-festival-mcp.git
cd china-festival-mcp

使用uvx运行（会自动安装依赖）

uvx --from . python -m src.server_fastmcp

🚀 使用方法

bash

从PyPI直接运行

uvx china-festival-mcp

或本地开发运行

uvx --from . python -m src.server_fastmcp

⚙️ MCP客户端配置

Claude Desktop配置

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

从PyPI安装（推荐）

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

本地开发

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

其他MCP客户端

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

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

📚 API文档

节假日工具

holiday_info

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

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

next_holiday

获取下一个节假日

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

current_year_holidays

获取当前年份所有节假日

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

current_year_work_days

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

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

农历工具

gregorian_to_lunar

公历转农历

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

lunar_to_gregorian

农历转公历

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

get_lunar_string

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

返回:
json
{
"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
获取二十四节气信息

返回:
json
{
"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

计算八字（四柱）

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

日期工具

get_weekday

根据公历日期计算星期几

返回:
json
{
"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项目开发，感谢原作者的贡献。

• 感谢所有贡献者
• 基于传统农历算法和现代计算方法
• 参考了多个开源农历转换项目