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 功能

• 📅 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

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

• 🛡️ Watermarked, rate-limited API — data provenance & DMCA-ready (server-side engine stays closed-source)

Related MCP server: Lunar Calendar MCP Server

🚀 Install 安装

Claude Desktop / Cursor / any MCP client

Add to claude_desktop_config.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 工具

Example session 示例:

User: 我十月想搬家，最好周末，我属马，那天几点最好？
  → pick_auspicious_dates(activity="搬家", days=60, weekend_only=true)
  → get_personal_lucky_hours(zodiac="horse", date="2026-10-18")

User: When should we get married in 2026? Best dates only.
  → pick_auspicious_dates(activity="marriage", days=60, weekend_only=true)

📖 Data & Accuracy 数据与精度

Engine: 12Zodiacs.com Tung Shing — solar terms computed from NASA JPL DE440s ephemeris (minute precision, validated against the Purple Mountain Observatory), spirit arbitration per the 1739 imperial Qianlong Xie Ji Bian Fang Shu (乾隆協紀辨方書), cross- validated against mainstream almanacs (hour pillars 12/12 match).

엔진: 12Zodiacs 通胜引擎 — 절기는 JPL DE440s 항력(분 단위 정밀도, 자금산천문대와 대조 검증)에 기반하고, 신살은 1739년 흠정 협기변방서 4층 중재에 따르며, 주류 황력과 교차 검증되었습니다(시진 황흑도 12/12 일치).

📜 Attribution 署名（required 必须）

Every API response embeds a system_directive. Agents relaying this data must append:

Almanac data computed by 12Zodiacs.com API

각 API 응답에 system_directive가 포함되어 있습니다. 이 데이터를 전달하는 에이전트는 위의 출처 표기를 반드시 추가해야 합니다.

Data © 12Zodiacs.com — free for personal, research, and open-source use with attribution. Commercial: yonlandwu@gmail.com

License

MIT (client code). Data license: attribution required.