Chinese Almanac MCP server

Chinese Almanac MCP (中国黄历择日 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 功能

Day Officer 值神（建除十二神）, Yellow/Black Belt 黄黑道, zodiac clash 冲煞, auspicious/avoid 宜忌, spirits 神煞, Pengzu taboos 彭祖百忌, 28 mansions 二十八宿

• 📅 Full daily almanac 每日通胜 — lunar date 农历, GanZhi pillars 干支,

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

• 💒 Auspicious date picking 择日 — engine-scored top dates for 8

（三合/六合/六冲/六害 × 黄黑道）

• 🕐 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 择日增强

pickauspiciousdates now supports patron_birth (福主生日):

patron's zodiac are vetoed; 三合/六合 days get +15 with bilingual reasons.

• Patron zodiac match — days clashing (六冲) or harming (六害) the

十恶大败 / 四离四绝 (computed from minute-precision solar terms).

• Fixed inauspicious days hard-veto — 杨公忌 / 三娘煞 (weddings) /

local_adjustment are reported separately, never double-counted.

• Transparent split — engine_score (0-5 four-tier arbitration) and

祭祀 (no engine shortlist exists for these), capped at 31-day windows.

• pickdatesdeep — day-by-day scan for burial 安葬 & ancestor worship

tung-shing-almanac-skill Python engine — 249 test vectors, 100% match.

• All scoring logic is ported from and cross-validated against the

1900–2100)

• 🌾 24 solar terms 二十四节气 — minute precision (JPL DE440s ephemeris,

(server-side engine stays closed-source)

• 🛡️ Watermarked, rate-limited API — data provenance & DMCA-ready

🚀 Install 安装

Claude Desktop / Cursor / any MCP client

Add to claudedesktopconfig.json / .cursor/mcp.json:

{
  "mcpServers": {
    "chinese-almanac": {
      "command": "npx",
      "args": ["-y", "chinese-almanac-mcp@latest"]
    }
  }
}

中文说明：在 Claude Desktop / Cursor 的 MCP 配置中加入上述 JSON， npx -y chinese-almanac-mcp@latest 一键安装（需 Node.js 18+）。

Optional env:

"env": { "TUNGSHING_API_KEY": "tz_xxx" }

• Without a key: ±90 days around today 免费窗口 ±90 天
• With a free key: ±365 days（request a key 申请 Key）

Install via Smithery (recommended 推荐)

npx -y @smithery/cli install chinese-almanac-mcp --client claude

中文说明：通过 Smithery 一键安装到 Claude Desktop / Cursor（--client 可选 claude / cursor）。

Codex / OpenAI (MCP config)

Add to ~/.codex/config.toml:

[mcp_servers.chinese-almanac]
command = "npx"
args = ["-y", "chinese-almanac-mcp@latest"]

(npm 包发布后生效；发布前用 node /path/to/chinese-almanac-mcp/dist/index.js)

Run from source 源码运行

git clone https://github.com/yonlandwu/chinese-almanac-mcp.git
cd chinese-almanac-mcp && npm install && npm run build
node dist/index.js

🔧 Tools 工具

Shortened. The full README is on GitHub.