china-festival-mcp

# 中国节假日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" } ``…