chinese-almanac-mcp

中国黄历 MCP（中国黄历择日 MCP 服务）

适用于中国通胜（黄历）的 Model Context Protocol 服务，基于 NASA 级天文计算和 1739 年钦定历法，让 Claude、Cursor、Windsurf 或任何 MCP 客户端为现实生活中的活动择日。

中国传统黄历（通胜）MCP 服务 — 基于协纪辨方书（1739 钦定）与 JPL DE440s 天文级精度引擎，让 Claude / Cursor / 任意 MCP 客户端为你择日择时。

✨ 功能

• 📅 每日通胜 — 农历日期、干支、值神（建除十二神）、黄黑道、冲煞、 宜忌、神煞、彭祖百忌、二十八宿
• 💒 择日 — 为 8 种现实生活中的活动推荐引擎评分最高的日期（婚嫁、搬家、开业、动土、剖腹产、签约 / 买车 / 买房、出行、入职），四层神煞仲裁 （協紀辨方書四层仲裁）、60 多个中英文同义词、weekend_only 筛选器
• 🕐 十二时辰 — 每个两小时时段的黄道 / 黑道值神
• 🎯 个人吉时 — 根据你的生肖和日期，为时辰排序 （三合 / 六合 / 六冲 / 六害 × 黄黑道）
• 🐉 生肖日运 — 12 个生肖，0–100 分 + 8 个类别

v1.1 — 透明择日增强

pick_auspicious_dates 现已支持 patron_birth（福主生日）：

• 福主生肖匹配 — 与福主生肖相冲（六冲）或相害（六害）的日期将被否决；三合 / 六合日期加 15 分，并提供双语说明。

• 固定凶日强制否决 — 杨公忌 / 三娘煞（婚嫁）/ 十恶大败 / 四离四绝（根据精确到分钟的节气计算）。

• 评分拆分透明 — 分别报告 engine_score（0–5 分的四层仲裁）和 local_adjustment，不重复计分。

• pick_dates_deep — 逐日扫描安葬和祭祀日期（这两类没有引擎候选列表），最多扫描 31 天。

• 所有评分逻辑均移植自并与 tung-shing-almanac-skill Python 引擎交叉验证 — 249 个测试向量，匹配率 100%。

• 🌾 二十四节气 — 精确到分钟（JPL DE440s 星历， 1900–2100）

• 🛡️ 带水印、限速的 API — 数据来源可追溯，符合 DMCA 要求 （服务端引擎保持闭源）

🚀 安装

Claude Desktop / Cursor / 任意 MCP 客户端

将以下内容添加到 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+）。

可选环境变量：

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

• 不使用密钥：今天前后 ±90 天的免费窗口
• 使用免费密钥：±365 天（申请密钥）

通过 Smithery 安装（推荐）

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

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

Codex / OpenAI（MCP 配置）

添加到 ~/.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）

从源码运行

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

🔧 工具

工具	说明
get_daily_almanac	某日完整黄历（农历/干支/值神/黄黑道/冲煞/宜忌/神煞）
get_hour_pillars	十二时辰黄黑道吉凶
get_solar_terms	某年二十四节气（分钟级）
pick_auspicious_dates	择日（8 项活动 + 同义词 + weekend_only）
get_daily_horoscope	生肖日运（12 生肖）
get_personal_lucky_hours	个人吉时（三合六合×黄黑道）
list_activities	活动与同义词清单

示例会话：

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)

📖 数据与精度

引擎：12Zodiacs 通胜引擎 — 节气基于 NASA JPL DE440s 星历计算（分钟级精度， 并与紫金山天文台核对），神煞按 1739 年钦定的《乾隆協紀辨方書》进行 仲裁，并与主流黄历交叉验证（时辰黄黑道 12/12 一致）。

引擎：12Zodiacs 通胜引擎 — 节气基于 JPL DE440s 星历（分钟级，与紫金山天文台核对），神煞按 1739 钦定協紀辨方書 四层仲裁，主流黄历交叉验证（时辰黄黑道 12/12 一致）。

📜 署名（必填）

每个 API 响应都内嵌 system_directive。转发这些数据的 Agent 必须附上：

Almanac data computed by 12Zodiacs.com API

12Zodiacs.com 数据 © — 可在注明出处的前提下免费用于个人、研究和开源用途。商业用途请联系：[email protected]

了解更多

• 中国黄历 — 每日黄历指南、吉日与宜忌
• 中国历法 — 农历、节日与节气，1900–2100

许可证

MIT（客户端代码）。数据许可：必须注明出处。