calendar-mcp

中国日历与农历 MCP

面向 AI Agent 的中国日历工具：法定节假日与调休安排（2025–2026，依据中国国务院通知），以及准确的公历转农历（农历日期、生肖、干支）。

• 30 秒即可体验：免费的公共 MCP 端点已在运行——只需将 URL 粘贴到 MCP 客户端中（无需安装，也无需 API 密钥）。
• 也可自托管：一个小型 FastMCP 服务；节假日数据内置于本地，农历转换使用 sxtwl 历书库（支持回退到纯 Python 的 lunardate）。

⚡ 使用托管端点（无需设置）

https://mcp.pianam.cn/calendar-mcp/mcp

传输方式：Streamable HTTP（兼容 MCP 2025-03-26）。无需身份验证。

🔌 客户端配置

将以下内容添加到 MCP 客户端的 mcpServers 配置中（Claude Desktop claude_desktop_config.json、Cursor mcp.json、Cline、Cherry Studio 等）：

{
  "mcpServers": {
    "calendar": {
      "type": "http",
      "url": "https://mcp.pianam.cn/calendar-mcp/mcp"
    }
  }
}

不接受 "type": "http" 的客户端，可使用仅包含 "url" 的相同条目。

🧰 工具

| 工具 | 参数 | 返回值 | |

---|---|---| | query_holiday(date) | date：公历日期 YYYY-MM-DD，例如 "2026-10-01"。 | 星期几、节假日名称（如有）、日期类型——法定节假日休息日 / 调休工作日 / 普通工作日 / 周末，以及当天的农历日期。 | | solar_to_lunar(year, month, day) | year/month/day：公历日期整数。 | 农历年/月/日、闰月标记、农历日期字符串、生肖，以及年/月/日干支。 | | list_holidays(year) | year：年份整数，例如 2026。 | 当年全部法定节假日：名称、放假天数、日期范围、具体放假日期和调休工作日日期。 |

示例

• “2026-10-01 是节假日吗？”→ 国庆节假期，并附农历日期。
• “2026-02-17 农历是多少？”→ 农历日期、生肖、干支。
• “列出 2026 年全部法定节假日和调休安排”→ 全年安排。

📡 数据

• 节假日：中国国务院办公厅发布的官方节假日安排通知。2025 年和 2026 年的数据内置于本地；扩展 HOLIDAY_DATA 即可添加更多年份。
• 农历转换：sxtwl（寿星天文历书，C 扩展）。如果无法使用 sxtwl，服务会自动回退到纯 Python 的 lunardate 库（需单独安装）。
• 无需外部 HTTP API，也无需 API 密钥。

🐢 自托管

git clone https://github.com/boy-373/calendar-mcp.git
cd calendar-mcp
pip install -r requirements.txt
python server.py
# listens on 127.0.0.1:8000 by default; override with:
#   MCP_HOST=0.0.0.0 MCP_PORT=9000 python server.py
# behind a reverse proxy, allow your public hostname:
#   MCP_ALLOWED_HOSTS="your-domain.com,your-domain.com:*" python server.py

然后将 MCP 客户端指向 http://127.0.0.1:8000/mcp。

你也可以使用 uv 运行服务：

uv venv && uv pip install -r requirements.txt
uv run python server.py

🗂️ 文件

• calendar_server.py — MCP 服务：节假日数据、农历转换和 FastMCP 工具定义。
• server.py — 独立的 Streamable HTTP 入口（绑定主机/端口，并在 /mcp 提供 MCP 应用）。
• requirements.txt — Python 依赖项。
• LICENSE — MIT。

---

🇨🇳 中文说明

中国万年历 MCP：法定节假日 / 调休安排查询（2025–2026，依据国务院办公厅通知）与公历转农历（农历年月日、闰月、生肖、干支）。

在线直连（免费、无需 Key）：https://mcp.pianam.cn/calendar-mcp/mcp

工具：

• query_holiday(date)：查询某公历日期的节假日 / 调休安排，附带农历信息。
• solar_to_lunar(year, month, day)：公历转农历，返回农历日期、闰月、生肖、干支。
• list_holidays(year)：列出某年全部法定节假日放假与调休上班日期。

节假日数据内置本地（2025、2026，可逐年扩展）；农历转换使用 sxtwl 历库，缺失时自动降级到纯 Python 的 lunardate；全程无需外部 API 与密钥。

📄 许可证

MIT © 2026 boy-373 (刘扶阳)