china-festival-mcp 0.1.1

中国节假日和农历转换MCP服务器

中国节假日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 (string, 可选): 日期，格式为 YYYY-MM-DD，不指定则查询当前日期

返回:

{
  "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

公历转农历

参数:

• date (string): 公历日期，格式为 YYYY-MM-DD

返回:

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

lunar_to_gregorian

农历转公历

参数:

• year (integer): 农历年份
• month (integer): 农历月份
• day (integer): 农历日期
• is_leap (boolean, 可选): 是否闰月，默认false

返回:

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

get_lunar_string

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

参数:

• date (string): 公历日期，格式为 YYYY-MM-DD

返回:

{
  "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

获取二十四节气信息

参数:

• date (string): 日期，格式为 YYYY-MM-DD

返回:

{
  "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

计算八字（四柱）

参数:

• date (string): 日期，格式为 YYYY-MM-DD
• hour (integer, 可选): 小时，0-23，默认12
• minute (integer, 可选): 分钟，0-59，默认0

返回:

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

日期工具

get_weekday

根据公历日期计算星期几

参数:

• date (string): 日期，格式为 YYYY-MM-DD，如：2024-01-01

返回:

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

🧪 测试

运行太阳历节气测试：

python test_solar_terms.py

📁 项目结构

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

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