Lunar Calendar Service（万年历）

lunar-calendar-service

🗓️ AI エージェント向けの中国語万年暦 MCP サービスです。新暦・旧暦の変換、二十四節気、法定祝日、黄暦の宜忌、八字・五行などを照会できます。

オンラインサービス： https://cheerful-trust-production-065e.up.railway.app/sse

---

すぐに接続する

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json を編集します。

{
  "mcpServers": {
    "lunar-calendar": {
      "url": "https://cheerful-trust-production-065e.up.railway.app/sse",
      "transport": "sse"
    }
  }
}

Cursor / Windsurf

MCP の設定に追加します。

Name: lunar-calendar
URL:  https://cheerful-trust-production-065e.up.railway.app/sse
Type: SSE

ローカルで実行（stdio モード）

git clone https://github.com/wouhao/lunar-calendar-service
cd lunar-calendar-service
uv sync

# Claude Desktop 本地接入
# claude_desktop_config.json:
# {
#   "mcpServers": {
#     "lunar-calendar": {
#       "command": "uv",
#       "args": ["run", "python", "server.py"],
#       "cwd": "/path/to/lunar-calendar-service"
#     }
#   }
# }
uv run python server.py

---

利用可能なツール（9 個）

基本機能

ツール	パラメーター	説明
get_date_info	date: YYYY-MM-DD	新暦・旧暦・干支・十二支・星座・節気・祝日の詳細情報を返します
solar_to_lunar	date: YYYY-MM-DD	新暦 → 旧暦
lunar_to_solar	year, month, day, leap_month?	旧暦 → 新暦（閏月に対応）
get_solar_terms	year: int	指定した年の二十四節気の日付をすべて照会します
is_holiday	date: YYYY-MM-DD	祝日かどうか／振替出勤日かどうか
get_holidays	year: int	指定した年の法定祝日一覧

黄暦

ツール	パラメーター	説明
get_almanac	date: YYYY-MM-DD	毎日の宜忌、吉神の方位（喜・福・財）、納音、彭祖百忌

高度な機能

ツール	パラメーター	説明
get_advanced_info	date: YYYY-MM-DD, hour?: 0-23	八字、五行、星宿、胎神、仏暦、道暦、黄道・黒道
get_lucky_days	start_date, end_date, purpose?	指定した期間内の吉日を照会します。用途も指定できます

---

使用例

接続後、Claude に次のように質問できます。

• 「今日はどんな日ですか？節気はありますか？」
• 「明日の黄暦では何が吉で、何が凶ですか？」
• 「2025 年の春節は何日ですか？」
• 「来月、開業に適した吉日はありますか？」
• 「2025 年の年間祝日スケジュールを調べてください」
• 「旧暦の1月1日は新暦の何日ですか？」

---

技術スタック

層	技術
言語	Python 3.11+
パッケージ管理	uv
基盤となる暦ライブラリ	lunar-python 1.4.8
サービス層	FastMCP（MCP SDK）
スキーマ	Pydantic v2
祝日データ	静的 JSON（2025 年）
デプロイ	Railway

---

ローカル開発

# 安装依赖
uv sync

# 运行测试
uv run pytest tests/ -v

# CLI 快捷查询
uv run python cli.py today

# 本地 HTTP/SSE 模式
MCP_TRANSPORT=sse PORT=8000 uv run python server.py
curl http://localhost:8000/health

---

Railway へのデプロイ

プロジェクトには railway.json と Procfile が含まれています。

1. このリポジトリをフォークします
2. Railway でプロジェクトを作成し、GitHub リポジトリをインポートします
3. デプロイ完了後、MCP エンドポイントは https://<your-app>.up.railway.app/sse です

---

ロードマップ

• Phase 1：コア機能（新暦・旧暦／節気／祝日）
• Phase 2：黄暦の拡充（宜忌／方位／納音）
• Phase 3：高度な機能（八字／五行／吉日）
• Phase 4：Railway へのクラウドデプロイ
• 2026 年の祝日データを追加
• さらに多くの年の祝日に対応

---

ライセンス

MIT

---

質問や提案があれば、お気軽に Issue または PR をお寄せください。