Japan Utils Mcp

japan-utils-mcp

AI エージェント（Claude、Cursor、Cline、Continue など）に日本固有のユーティリティを提供する MCP サーバーです。日本に関するタスクで必要になるものの、汎用 LLM では確実に正しく扱えない、小さな日本固有機能セットをエージェントに提供します。

• 🗓️ 元号 ↔ 西暦 — 令和8年 ↔ 2026
• 🔤 漢字 → ヘボン式ローマ字 — 山田太郎 → yamada tarou
• 📮 郵便番号検索 — 150-0001 → 東京都 渋谷区 神宮前
• 🎌 国民の祝日カレンダー — 2026-05-03 は祝日ですか？2026 年全体ではどうですか？
• 🅰️ かな変換 — ひらがな ↔ カタカナ ↔ 半角カタカナ
• 📏 文字幅の正規化 — ASCII、数字、かなの全角 ↔ 半角
• 👤 氏名の分割 — 山田太郎 → 姓 山田 + 名 太郎（統計モデル）

メンテナンスの行き届いた日本語ライブラリ（jpholiday、posuto、pykakasi、jaconv、namedivider-python）をベースに、MCP ツールとしてラップしています。読みのルール、元号の計算、郵便番号データ、氏名分割のヒューリスティックを再実装することなく、あらゆる AI エージェントから呼び出せます。

このプロジェクトを作った理由

汎用 LLM は日本固有のデータについて幻覚を起こします。

• 「令和8年は西暦何年？」— 間違えることがよくあります
• 「山田太郎をローマ字に変換して」— 半分の確率で姓を間違えます
• 「郵便番号 150-0001 の住所は？」— もっともらしいだけの誤情報を作り出します
• 「5月3日は日本の祝日？」— 推測で答えます

この MCP は、決定的な答えを提供します。

ツール

ツール	機能
era_to_western	令和8年 / R8 / Reiwa 8 / 令和元年 → 西暦年 + 元号のメタデータ
western_to_era	2026 → 元号の漢字（令和）、英語表記（Reiwa）、元号年（8）、書式設定済み文字列
kanji_to_romaji	日本語の混在テキスト → ヘボン式ローマ字 + ひらがなの読み
lookup_postal_code	7 桁の日本の郵便番号 → 都道府県 / 市区町村 / 地域（かなの読み付き）
is_holiday	日付文字列 → 国民の祝日かどうか + 日本語名 + 曜日
list_holidays	年 → その年の国民の祝日すべて
convert_kana	ひらがな ↔ カタカナ ↔ 半角カタカナ（任意の方向に変換）
normalize_width	ASCII、数字、かなの全角 ↔ 半角（カテゴリごとの制御機能付き）
split_japanese_name	日本人のフルネーム → 姓 + 名（信頼度付き統計モデル）

すべてのツールは構造化 JSON を返します。完全なスキーマと例については、src/japan_utils_mcp/server.py のツールドックストリングを参照してください。

インストール

uvx で実行（インストール不要 — 推奨）

uvx japan-utils-mcp

以上です。uv に含まれる uvx が、グローバルの Python 環境から分離した状態で、インストールと実行を一度に処理します。

ソースから

git clone https://github.com/vivek081166/japan-utils-mcp.git
cd japan-utils-mcp
uv sync
uv run japan-utils-mcp

設定

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

{
  "mcpServers": {
    "japan-utils": {
      "command": "uvx",
      "args": ["japan-utils-mcp"]
    }
  }
}

Claude Code

claude mcp add japan-utils -- uvx japan-utils-mcp

Cursor / Cline / Continue

Claude Desktop と同じ JSON スニペットを、それぞれの MCP 設定ファイルに追加します。

使用例

接続後、エージェントに次のようなことを尋ねてみてください。

令和8年は西暦何年ですか？ → era_to_western("令和8年") → 2026

郵便番号 150-0001 の住所はどこですか？ → lookup_postal_code("150-0001") → 東京都 渋谷区 神宮前

山田太郎をローマ字に変換してください。 → kanji_to_romaji("山田太郎") → yamada tarou

2026年5月3日は日本の祝日ですか？ → is_holiday("2026-05-03") → 憲法記念日（憲法記念日）

2026年の日本の祝日をすべて一覧表示してください。 → list_holidays(2026) → 名称と日付を含む 18 件の祝日

ヤマダタロウをひらがなに変換してください。 → convert_kana("ヤマダタロウ", "hiragana") → やまだたろう

ＡＢＣ１２３を半角に正規化してください。 → normalize_width("ＡＢＣ１２３", "to_half") → ABC123

長谷川健太を姓と名に分けてください。 → split_japanese_name("長谷川健太") → 長谷川 / 健太

注意事項

• 人名のローマ字表記には最も一般的な読みを使用します。特殊な読み方をする固有名詞は正しく変換されない場合があります。これは、判別に必要なコンテキストがない状態で漢字をローマ字に変換する場合の根本的な制約です。
• 郵便番号データセットは posuto ライブラリ経由で提供され、日本郵便の毎月のKEN_ALLに基づいて更新されます。最新のデータが必要な場合は、posuto を定期的に更新してください。
• 祝日は国民の祝日のみを対象としており、企業独自または地域の記念日は含まれません。
• 元号変換は明治から令和までに対応しています。それ以前の元号には対応していません。

開発

git clone https://github.com/vivek081166/japan-utils-mcp.git
cd japan-utils-mcp
uv sync
uv run python -c "from japan_utils_mcp.server import era_to_western; print(era_to_western('令和8年'))"

ライセンス

MIT