中国节假日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项目开发，感谢原作者的贡献。