jp-dates MCP Server 🗾📅

日本の祝日・和暦・日付情報を Claude に提供する MCP (Model Context Protocol) サーバーです。

An MCP server that gives Claude accurate knowledge of Japanese national holidays, wareki (era) conversion, and date info. Works fully offline — no API keys required.

✨ できること / Features

Claude にこんな質問が正確に即答できるようになります:

• 「来月の祝日はいつ?」

• 「次の連休まであと何日?」

• 「令和6年って西暦何年?」「1989年1月7日は昭和?平成?」

• 「2026年のシルバーウィークはいつ?」

• ✅ APIキー不要・完全オフライン(祝日はアルゴリズムで算出)

• ✅ 振替休日・国民の休日・2020/2021年の五輪特例に対応

• ✅ 対応範囲: 祝日 2020〜2099年 / 和暦 1868年(明治)以降

Related MCP server: JP Business Calendar MCP

🚀 セットアップ / Setup

1. インストール

Node.js 18 以上が必要です。

git clone https://github.com/h-kazuki-pixel/jp-dates-mcp-server.git
cd jp-dates-mcp-server
npm install
npm run build

npm install の時点で prepare スクリプトによりビルドが実行されます。npm run build を省いても dist/ は生成されますが、明示的に実行しても問題ありません。

2. Claude Desktop に登録

claude_desktop_config.json に以下を追加します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jp-dates": {
      "command": "node",
      "args": ["/absolute/path/to/jp-dates-mcp-server/dist/index.js"]
    }
  }
}

Claude Desktop を再起動すると、🔌アイコンからツールが確認できます。

3. 使ってみる

Claude にそのまま話しかけるだけです:

「今年の残りの祝日を教えて」 「昭和58年は西暦何年?」

🧪 テスト / Tests

npm test

テスト30件。追加の依存はありません(Node標準の node --test のみ)。

祝日の正しさは、内閣府の公表データそのものと突き合わせて検証しています。

• 照合元: 内閣府「国民の祝日について」の公表CSV(test/fixtures/syukujitsu.csv として同梱。文字コードのみ Shift_JIS → UTF-8 に変換し、内容は無改変) https://www8.cao.go.jp/chosei/shukujitsu/syukujitsu.csv

• CSVと本サーバーの対応範囲が重なる 2020年〜CSV最終年を全件・日付と名称の両方で照合します

• CSVは振替休日と国民の休日をどちらも「休日」と記載するため、その1点のみ名称を読み替えて比較します

• 加えて境界ケースを個別に検証: 五輪特例(2020・2021の海の日/スポーツの日/山の日の移動)、日曜が祝日の場合の振替、翌日も祝日の場合の繰り下がり、国民の休日(敬老の日と秋分の日に挟まれた平日)、春分・秋分の変動、改元境界の和暦変換(1989-01-07/08、2019-04-30/05-01)

CSVが更新されたら差し替えるだけで、対象年が自動的に広がります。

MCP Inspector で対話的に試すこともできます:

npx @modelcontextprotocol/inspector node dist/index.js

📝 祝日計算について / Notes

• 祝日は法律(国民の祝日に関する法律)のルールに基づきアルゴリズムで算出しています

• 春分・秋分は天文計算の近似式を使用(1980〜2099年で有効)

• 対応範囲は 2020〜2099年です。範囲外の年を指定した場合はエラーを返します(誤った値を返しません)

• 将来の法改正には追従が必要です。誤りを見つけたら Issue で教えてください!

🤝 コントリビュート / Contributing

Issue・Pull Request 歓迎です! 機能要望(六曜、旧暦、営業日計算など)もお待ちしています。

📄 License

MIT