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は、それらに対して決定論的な回答を提供します。

ツール

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

インストール

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

uvx japan-utils-mcp

以上です。uvx（uv に含まれる）は、グローバルな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