china-festival-mcp
为 AI Agent 提供准确的法定节假日、调休安排、中国传统节日、农历转换、二十四节气和八字计算功能。西方节日都是固定公历日期，不需要查询工具。
Documentation
中国节假日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
}`month_calendar`
查询指定月份的完整日历，包含节假日和调休信息。不指定年份时查询当前年份，不指定月份时查询当前月份。
参数:
- `month`: 月份，1-12
- `year`: 年份
返回:
{
"year": 2024,
"month": 6,
"month_name": "2024年6月",
"days": [
{
"date": "2024-06-10",
"day": 10,
"name": "端午节",
"type": "holiday",
"is_holiday": true,
"is_work_day": false,
"note": "法定节假日",
"weekday_name_cn": "星期一",
"weekday_name_en": "Monday"
}
],
"weeks": [],
"holidays": [],
"work_days": [],
"total_days": 30,
"holiday_count": 1,
"work_day_count": 0
}农历工具
`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项目开发，感谢原作者的贡献。
Frequently asked questions
What is china-festival-mcp?
china-festival-mcp is 为 AI Agent 提供准确的法定节假日、调休安排、中国传统节日、农历转换、二十四节气和八字计算功能。西方节日都是固定公历日期，不需要查询工具。
How do I install china-festival-mcp?
Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.
Is china-festival-mcp open source?
Yes — it is hosted on GitHub at https://github.com/Eis4TY/china-festival-mcp and has 1 stars.
Related MCP tools
openhands🙌 OpenHands: Code Less, Make More for the Model Context Protocol. Enhance AI assistants with powerful integrations. Python-based implementation.
mem0Universal memory layer for AI Agents; Announcing OpenMemory MCP - local and secure memory management. Python-based implementation.
chatgpt-on-wechat基于大模型搭建的聊天机器人，同时支持 微信公众号、企业微信应用、飞书、钉钉 等接入，可选择ChatGPT/Claude/DeepSeek/文心一言/讯飞星火/通义千问/ Gemini/GLM-4/Kimi/LinkAI，能处理文本、语音和图片，访问操作系统和互联网，支持基于自有知识库进行定制企业智能客服。
gpt-researcherAn LLM agent that conducts deep research (local and web) on any given topic and generates a long report with citations. Built for the Model Context Protocol to
fastmcp🚀 The fast, Pythonic way to build MCP servers and clients Trusted by 19900+ developers. Trusted by 19900+ developers. Trusted by 19900+ developers.
maxkb🔥 MaxKB is an open-source platform for building enterprise-grade agents. MaxKB 是强大易用的开源企业级智能体平台。 for the Model Context Protocol. Enhance AI assistants with po
Run your own MCP server? See who uses it and what to fix.
Measure it with TrackMCP