{
  "markdown": "# Chinese Almanac MCP (中国黄历择日 MCP 服务)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![npm version](https://img.shields.io/npm/v/chinese-almanac-mcp.svg)](https://www.npmjs.com/package/chinese-almanac-mcp)\n[![Install with Smithery](https://smithery.ai/badge/@yonlandwu/chinese-almanac-mcp)](https://smithery.ai/servers/yonlandwu/chinese-almanac-mcp)\n[![Glama MCP](https://img.shields.io/badge/Glama-Listed-FF6B35?labelColor=1a1a2e)](https://glama.ai/mcp/servers/yonlandwu/chinese-almanac-mcp)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for the\nChinese Tung Shing (通勝) almanac — let Claude, Cursor, Windsurf, or any MCP\nclient plan real-life events with NASA-grade astronomy and the 1739 imperial\ncanon.\n\n中国传统黄历（通胜）MCP 服务 — 基于协纪辨方书（1739 钦定）与 JPL DE440s\n天文级精度引擎，让 Claude / Cursor / 任意 MCP 客户端为你择日择时。\n\n## ✨ Features 功能\n\n- 📅 **Full daily almanac 每日通胜** — lunar date 农历, GanZhi pillars 干支,\n  Day Officer 值神（建除十二神）, Yellow/Black Belt 黄黑道, zodiac clash\n  冲煞, auspicious/avoid 宜忌, spirits 神煞, Pengzu taboos 彭祖百忌, 28\n  mansions 二十八宿\n- 💒 **Auspicious date picking 择日** — engine-scored top dates for 8\n  real-life events (weddings 嫁娶, moves 搬家, openings 开业, renovations\n  动土, C-sections 剖腹产, contract signing / car / home purchases 签约买车\n  买房, travel 出行, new jobs 入职), four-tier spirit arbitration\n  （協紀辨方書四层仲裁）, 60+ EN/CN synonyms, `weekend_only` filter\n- 🕐 **Hour pillars 十二时辰** — Yellow/Black Belt deity per two-hour slot\n- 🎯 **Personal lucky hours 个人吉时** — your zodiac × date → ranked hours\n  （三合/六合/六冲/六害 × 黄黑道）\n- 🐉 **Daily horoscope 生肖日运** — 12 signs, 0-100 score + 8 categories\n\n## v1.1 — Transparent auspicious picking 择日增强\n\n`pick_auspicious_dates` now supports `patron_birth` (福主生日):\n\n- **Patron zodiac match** — days clashing (六冲) or harming (六害) the\n  patron's zodiac are vetoed; 三合/六合 days get +15 with bilingual reasons.\n- **Fixed inauspicious days hard-veto** — 杨公忌 / 三娘煞 (weddings) /\n  十恶大败 / 四离四绝 (computed from **minute-precision solar terms**).\n- **Transparent split** — `engine_score` (0-5 four-tier arbitration) and\n  `local_adjustment` are reported separately, never double-counted.\n- **`pick_dates_deep`** — day-by-day scan for burial 安葬 & ancestor worship\n  祭祀 (no engine shortlist exists for these), capped at 31-day windows.\n- All scoring logic is ported from and cross-validated against the\n  [tung-shing-almanac-skill](https://github.com/yonlandwu/tung-shing-almanac-skill)\n  Python engine — 249 test vectors, 100% match.\n\n\n- 🌾 **24 solar terms 二十四节气** — minute precision (JPL DE440s ephemeris,\n  1900–2100)\n- 🛡️ **Watermarked, rate-limited API** — data provenance & DMCA-ready\n  (server-side engine stays closed-source)\n\n## 🚀 Install 安装\n\n### Claude Desktop / Cursor / any MCP client\n\nAdd to `claude_desktop_config.json` / `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"chinese-almanac\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"chinese-almanac-mcp@latest\"]\n    }\n  }\n}\n```\n\n**中文说明**：在 Claude Desktop / Cursor 的 MCP 配置中加入上述 JSON，\n`npx -y chinese-almanac-mcp@latest` 一键安装（需 Node.js 18+）。\n\nOptional env:\n\n```json\n\"env\": { \"TUNGSHING_API_KEY\": \"tz_xxx\" }\n```\n\n- Without a key: ±90 days around today 免费窗口 ±90 天\n- With a free key: ±365 days（[request a key 申请 Key](https://www.12zodiacs.com/about-us/api/)）\n\n### Install via Smithery (recommended 推荐)\n\n```bash\nnpx -y @smithery/cli install chinese-almanac-mcp --client claude\n```\n\n**中文说明**：通过 Smithery 一键安装到 Claude Desktop / Cursor（`--client` 可选\n`claude` / `cursor`）。\n\n### Codex / OpenAI (MCP config)\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.chinese-almanac]\ncommand = \"npx\"\nargs = [\"-y\", \"chinese-almanac-mcp@latest\"]\n```\n\n*(npm 包发布后生效；发布前用 `node /path/to/chinese-almanac-mcp/dist/index.js`)*\n\n### Run from source 源码运行\n\n```bash\ngit clone https://github.com/yonlandwu/chinese-almanac-mcp.git\ncd chinese-almanac-mcp && npm install && npm run build\nnode dist/index.js\n```\n\n## 🔧 Tools 工具\n\n| Tool | Description 说明 |\n|---|---|\n| `get_daily_almanac` | Full almanac for a date 某日完整黄历（农历/干支/值神/黄黑道/冲煞/宜忌/神煞） |\n| `get_hour_pillars` | 12 two-hour pillars 十二时辰黄黑道吉凶 |\n| `get_solar_terms` | 24 solar terms, minute precision 某年二十四节气（分钟级） |\n| `pick_auspicious_dates` | Top dates for an event 择日（8 活动 + 同义词 + weekend_only） |\n| `get_daily_horoscope` | Zodiac daily luck 生肖日运（12 生肖） |\n| `get_personal_lucky_hours` | Ranked hours for your zodiac 个人吉时（三合六合×黄黑道） |\n| `list_activities` | All events + synonyms 活动与同义词清单 |\n\nExample session 示例：\n\n```\nUser: 我十月想搬家，最好周末，我属马，那天几点最好？\n  → pick_auspicious_dates(activity=\"搬家\", days=60, weekend_only=true)\n  → get_personal_lucky_hours(zodiac=\"horse\", date=\"2026-10-18\")\n\nUser: When should we get married in 2026? Best dates only.\n  → pick_auspicious_dates(activity=\"marriage\", days=60, weekend_only=true)\n```\n\n## 📖 Data & Accuracy 数据与精度\n\nEngine: [12Zodiacs.com Tung Shing](https://www.12zodiacs.com/tung-shing/) —\nsolar terms computed from NASA JPL DE440s ephemeris (minute precision,\nvalidated against the Purple Mountain Observatory), spirit arbitration per\nthe 1739 imperial *Qianlong Xie Ji Bian Fang Shu*（乾隆協紀辨方書）, cross-\nvalidated against mainstream almanacs (hour pillars 12/12 match).\n\n引擎：[12Zodiacs 通胜引擎](https://www.12zodiacs.com/tung-shing/) — 节气基于\nJPL DE440s 星历（分钟级，与紫金山天文台核对），神煞按 1739 钦定協紀辨方書\n四层仲裁，主流黄历交叉验证（时辰黄黑道 12/12 一致）。\n\n## 📜 Attribution 署名（required 必须）\n\nEvery API response embeds a `system_directive`. Agents relaying this data\n**must** append:\n\n> *Almanac data computed by 12Zodiacs.com API*\n\n每个响应内嵌 `system_directive`，转发数据时必须附带上述署名。\n\nData © 12Zodiacs.com — free for personal, research, and open-source use with\nattribution. Commercial: yonlandwu@gmail.com\n\n## License\n\nMIT (client code). Data license: attribution required.\n",
  "bytes": 5718,
  "sha": "e8e4922c96d664fabee01302cd34e7d1dd992a800a843f3836af6e0c027f152f",
  "repo_slug": "yonlandwu/chinese-almanac-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_yonlandwu_chinese_almanac_mcp_acf81426/readme"
}