chinese-almanac-mcp

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

Model Context Protocol に対応した、中国の通勝（Tung Shing）暦向けサーバーです。NASA 級の天文学と 1739 年の皇室公認典籍を用いて、Claude、Cursor、Windsurf、または任意の MCP クライアントが実生活の予定を計画できます。

中国伝統の黄暦（通勝）MCP サービスです。協紀辨方書（1739 年に皇帝が制定）と JPL DE440s に基づく天文学的精度のエンジンを使用し、Claude／Cursor／任意の MCP クライアントで、日取りや時刻を選べます。

✨ 機能

• 📅 毎日の通勝 — 旧暦の日付、干支の柱、日神（建除十二神）、黄道／黒道、生肖の冲煞、吉凶、神煞、彭祖百忌、二十八宿
• 💒 吉日選び — 実生活の 8 種類のイベント（結婚、引っ越し、開業、改装、帝王切開、契約／車／家の購入、旅行、入社）について、エンジンがスコア付けした上位の日付を提示します。神煞の 4 段階の判定、英語／中国語の 60 以上の同義語、weekend_only フィルターに対応しています。
• 🕐 十二時辰 — 2 時間ごとの時間帯における黄道／黒道の神
• 🎯 個人の吉時 — あなたの生肖と日付から、吉時をランキング形式で提示します（三合／六合／六冲／六害 × 黄道／黒道）
• 🐉 毎日の生肖運勢 — 12 の生肖、0～100 のスコアと 8 項目のカテゴリー

v1.1 — 吉日選びの透明性向上

pick_auspicious_dates が patron_birth（依頼主の誕生日）に対応しました。

• 依頼主の生肖との相性 — 依頼主の生肖と六冲または六害になる日は除外します。三合／六合の日には、二言語の理由とともに +15 点を加算します。

• 固定の凶日を確実に除外 — 楊公忌／三娘煞（結婚の場合）／十悪大敗／四離四絶（分単位の精度で計算した節気に基づきます）。

• スコアの内訳を明確化 — engine_score（4 段階判定、0～5 点）と local_adjustment を個別に報告し、二重計上は行いません。

• pick_dates_deep — 埋葬と祖先供養について、1 日ずつスキャンします（これらにはエンジンの候補リストがありません）。期間は最長 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	12の二時間ごとの時柱と黄道・黒道の吉凶
get_solar_terms	24節気（分単位）
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.com Tung Shing — 節気は NASA JPL DE440s 暦表に基づいて計算（分単位、 紫金山天文台との照合済み）。神煞の判定は、1739年の皇帝勅撰書 Qianlong Xie Ji Bian Fang Shu（乾隆協紀辨方書）に基づく4層の仲裁を行い、 一般的な暦と相互検証済み（時柱の黄道・黒道は12/12一致）。

📜 クレジット表記（必須）

すべての API レスポンスには system_directive が埋め込まれています。このデータを中継するエージェントは、必ず次のクレジットを付記してください。

12Zodiacs.com API によって計算された暦データ

データ © 12Zodiacs.com — 個人利用、研究、オープンソースでの利用は、クレジット表記を条件に無料です。商用利用：[email protected]

詳細を見る

• 中国暦 — 毎日の暦の指針、吉日、宜忌
• 中国のカレンダー — 旧暦、祭日、節気、1900～2100年

ライセンス

MIT（クライアントコード）。データライセンス：クレジット表記が必要です。