yonlandwu/chinese-almanac-mcp

A Model Context Protocol server for the
Chinese Tung Shing (通勝) almanac — let Claude, Cursor, Windsurf, or any MCP
client plan real-life events with NASA-grade astronomy and the 1739 imperial
canon.
中国传统黄历（通胜）MCP 服务 — 基于协纪辨方书（1739 钦定）与 JPL DE440s
天文级精度引擎，让 Claude / Cursor / 任意 MCP 客户端为你择日择时。
✨ Features 功能
- 📅 **Full daily almanac 每日通胜** — lunar date 农历, GanZhi pillars 干支,
Day Officer 值神（建除十二神）, Yellow/Black Belt 黄黑道, zodiac clash
冲煞, auspicious/avoid 宜忌, spirits 神煞, Pengzu taboos 彭祖百忌, 28
mansions 二十八宿
- 💒 **Auspicious date picking 择日** — engine-scored top dates for 8
real-life events (weddings 嫁娶, moves 搬家, openings 开业, renovations
动土, C-sections 剖腹产, contract signing / car / home purchases 签约买车
买房, travel 出行, new jobs 入职), four-tier spirit arbitration
（協紀辨方書四层仲裁）, 60+ EN/CN synonyms, weekend_only filter
- 🕐 **Hour pillars 十二时辰** — Yellow/Black Belt deity per two-hour slot
- 🎯 **Personal lucky hours 个人吉时** — your zodiac × date → ranked hours
（三合/六合/六冲/六害 × 黄黑道）
- 🐉 **Daily horoscope 生肖日运** — 12 signs, 0-100 score + 8 categories
v1.1 — Transparent auspicious picking 择日增强
pick_auspicious_dates now supports patron_birth (福主生日):
- **Patron zodiac match** — days clashing (六冲) or harming (六害) the
patron's zodiac are vetoed; 三合/六合 days get +15 with bilingual reasons.
- **Fixed inauspicious days hard-veto** — 杨公忌 / 三娘煞 (weddings) /
十恶大败 / 四离四绝 (computed from **minute-precision solar terms**).
- **Transparent split** — engine_score (0-5 four-tier arbitration) and
local_adjustment are reported separately, never double-counted.
- **pick_dates_deep** — day-by-day scan for burial 安葬 & ancestor worship
祭祀 (no engine shortlist exists for these), capped at 31-day windows.
- All scoring logic is ported from and cross-validated against the
tung-shing-almanac-skill
Python engine — 249 test vectors, 100% match.
- 🌾 **24 solar terms 二十四节气** — minute precision (JPL DE440s ephemeris,
1900–2100)
- 🛡️ **Watermarked, rate-limited API** — data provenance & DMCA-ready
(server-side engine stays closed-source)
🚀 Install 安装
Claude Desktop / Cursor / any MCP client
Add to claude_desktop_config.json / .cursor/mcp.json:
**中文说明**：在 Claude Desktop / Cursor 的 MCP 配置中加入上述 JSON，
npx -y chinese-almanac-mcp@latest 一键安装（需 Node.js 18+）。
Optional env:
- Without a key: ±90 days around today 免费窗口 ±90 天
- With a free key: ±365 days（request a key 申请 Key）
Install via Smithery (recommended 推荐)
**中文说明**：通过 Smithery 一键安装到 Claude Desktop / Cursor（--client 可选
claude / cursor）。
Codex / OpenAI (MCP config)
Add to ~/.codex/config.toml:
*(npm 包发布后生效；发布前用 node /path/to/chinese-almanac-mcp/dist/index.js)*
Run from source 源码运行
🔧 Tools 工具
| Tool | Description 说明 |
|---|---|
| get_daily_almanac | Full almanac for a date 某日完整黄历（农历/干支/值神/黄黑道/冲煞/宜忌/神煞） |
| get_hour_pillars | 12 two-hour pillars 十二时辰黄黑道吉凶 |
| get_solar_terms | 24 solar terms, minute precision 某年二十四节气（分钟级） |
| pick_auspicious_dates | Top dates for an event 择日（8 活动 + 同义词 + weekend_only） |