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:```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 模式)```bash
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 |
---
## 本地开发```bash
# 安装依赖
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:
- Fork 本仓库
- 在 Railway 创建项目,导入 GitHub 仓库
- 部署完成后,MCP endpoint 为
https://.up.railway.app/sse
路线图
- [x] Phase 1:核心功能(公农历/节气/节假日)
- [x] Phase 2:黄历增强(宜忌/方位/纳音)
- [x] Phase 3:高级功能(八字/五行/吉日)
- [x] Phase 4:Railway 云端部署
- [ ] 补充 2026 年节假日数据
- [ ] 更多年份节假日支持
License
MIT
> 如有问题或建议,欢迎提 Issue 或 PR。
