lunar-calendar-service

🗓️ 给 AI Agent 使用的中文万年历 MCP 服务。提供公农历转换、二十四节气、法定节假日、黄历宜忌、八字五行等查询能力。

线上服务： https://cheerful-trust-production-065e.up.railway.app/sse

---

快速接入

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "lunar-calendar": {
      "url": "https://cheerful-trust-production-065e.up.railway.app/sse",
      "transport": "sse"
    }
  }
}

Cursor / Windsurf

在 MCP 设置里添加：

Name: lunar-calendar
URL:  https://cheerful-trust-production-065e.up.railway.app/sse
Type: SSE

本地运行（stdio 模式）

git clone https://github.com/wouhao/lunar-calendar-service
cd lunar-calendar-service
uv sync

# Claude Desktop 本地接入
# claude_desktop_config.json:
# {
#   "mcpServers": {
#     "lunar-calendar": {
#       "command": "uv",
#       "args": ["run", "python", "server.py"],
#       "cwd": "/path/to/lunar-calendar-service"
#     }
#   }
# }
uv run python server.py

---

可用工具（9 个）

基础功能

工具	参数	说明
get_date_info	date: YYYY-MM-DD	返回公历/农历/干支/生肖/星座/节气/节假日完整信息
solar_to_lunar	date: YYYY-MM-DD	公历 → 农历
lunar_to_solar	year, month, day, leap_month?	农历 → 公历（支持闰月）
get_solar_terms	year: int	查询某年全部 24 节气日期
is_holiday	date: YYYY-MM-DD	是否节假日 / 调休上班
get_holidays	year: int	某年全部法定节假日列表

黄历

工具	参数	说明
get_almanac	date: YYYY-MM-DD	每日宜忌、吉神方位（喜/福/财）、纳音、彭祖百忌

高级

工具	参数	说明
get_advanced_info	date: YYYY-MM-DD, hour?: 0-23	八字、五行、星宿、胎神、佛历、道历、黄道黑道
get_lucky_days	start_date, end_date, purpose?	查询范围内的黄道吉日，可指定用途

---

使用示例

接入后，你可以这样问 Claude：

• "今天是什么日子？有没有节气？"
• "明天黄历上宜什么忌什么？"
• "2025 年春节是哪天？"
• "下个月有哪些黄道吉日适合开业？"
• "帮我查一下 2025 年全年节假日安排"
• "农历正月初一是公历几号？"

---

技术栈

层次	技术
语言	Python 3.11+
包管理	uv
底层历法库	lunar-python 1.4.8
服务层	FastMCP (MCP SDK)
Schema	Pydantic v2
节假日数据	静态 JSON（2025 年）
部署	Railway

---

本地开发

# 安装依赖
uv sync

# 运行测试
uv run pytest tests/ -v

# CLI 快捷查询
uv run python cli.py today

# 本地 HTTP/SSE 模式
MCP_TRANSPORT=sse PORT=8000 uv run python server.py
curl http://localhost:8000/health

---

自行部署到 Railway

项目已包含 railway.json 和 Procfile：

1. Fork 本仓库
2. 在 Railway 创建项目，导入 GitHub 仓库
3. 部署完成后，MCP endpoint 为 https://<your-app>.up.railway.app/sse

---

路线图

• Phase 1：核心功能（公农历/节气/节假日）
• Phase 2：黄历增强（宜忌/方位/纳音）
• Phase 3：高级功能（八字/五行/吉日）
• Phase 4：Railway 云端部署
• 补充 2026 年节假日数据
• 更多年份节假日支持

---

License

MIT

---

如有问题或建议，欢迎提 Issue 或 PR。