English Français العربية

io.github.yonlandwu/chinese-almanac-mcp

Official registry Games, sports and entertainment

Chinese almanac (黄历) MCP: date selection, daily almanac, solar terms, zodiac horoscopes.

Source code Documentation

What can you do with io.github.yonlandwu/chinese-almanac-mcp?

  • 📅 Full daily almanac 每日通胜 — lunar date 农历, GanZhi pillars 干支,
  • 💒 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

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package chinese-almanac-mcp
Claude Code 
claude mcp add chinese-almanac-mcp -e 'TUNGSHING_API_KEY=<your tungshing_api_key>' -- npx -y chinese-almanac-mcp@1.0.2
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "chinese-almanac-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "chinese-almanac-mcp@1.0.2"
            ],
            "env": {
                "TUNGSHING_API_KEY": "<your tungshing_api_key>"
            }
        }
    }
}

Environment variables

  • TUNGSHING_API_KEY secret Optional free API key from 12Zodiacs.com for ±365-day range (anonymous allows ±90 days).

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. Chinese Almanac MCP (中国黄历择日 MCP 服务)
  2. ✨ Features 功能
  3. v1.1 — Transparent auspicious picking 择日增强
  4. 🚀 Install 安装
  5. 🔧 Tools 工具
  6. 📖 Data & Accuracy 数据与精度
  7. 📜 Attribution 署名（required 必须）
  8. Learn more
  9. License

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

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:

{
  "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" }
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 工具

ToolDescription 说明
get_daily_almanacFull almanac for a date 某日完整黄历（农历/干支/值神/黄黑道/冲煞/宜忌/神煞）
get_hour_pillars12 two-hour pillars 十二时辰黄黑道吉凶
get_solar_terms24 solar terms, minute precision 某年二十四节气（分钟级）
pick_auspicious_datesTop dates for an event 择日（8 活动 + 同义词 + weekend_only）
get_daily_horoscopeZodiac daily luck 生肖日运（12 生肖）
get_personal_lucky_hoursRanked hours for your zodiac 个人吉时（三合六合×黄黑道）
list_activitiesAll events + synonyms 活动与同义词清单

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 钦定協紀辨方書 四层仲裁，主流黄历交叉验证（时辰黄黑道 12/12 一致）。

📜 Attribution 署名（required 必须）

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

Almanac data computed by 12Zodiacs.com API

每个响应内嵌 system_directive，转发数据时必须附带上述署名。

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

Learn more

License

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

Frequently asked questions

What is io.github.yonlandwu/chinese-almanac-mcp?

Chinese almanac (黄历) MCP: date selection, daily almanac, solar terms, zodiac horoscopes.

How do I install io.github.yonlandwu/chinese-almanac-mcp?

It runs on your machine. In Claude Code: claude mcp add chinese-almanac-mcp -e 'TUNGSHING_API_KEY=<your tungshing_api_key>' -- npx -y chinese-almanac-mcp@1.0.2. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.yonlandwu/chinese-almanac-mcp need an API key?

Yes. It expects TUNGSHING_API_KEY, which you set in its configuration.

Is io.github.yonlandwu/chinese-almanac-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.yonlandwu/chinese-almanac-mcp?

It is published by yonlandwu. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.