jp-postal-code-mcp

日本郵便の公開データから、郵便番号に対応する町域や、住所に対応する郵便番号を調べられます。大口事業所や私書箱の個別郵便番号も照会できます。

利用前に

uv と Git が必要です。Python 3.12以上に対応しています。APIキーの設定は不要です。

Related MCP server: Japan Area Code MCP Server

MCPクライアントに登録する

公開GitHubリポジトリから uvx で起動します。初回は依存関係の準備に時間がかかることがあります。

Codex

codex mcp add jp-postal-code-mcp -- uvx --python 3.12 --from git+https://github.com/koizumikento/jp-postal-code-mcp.git@main jp-postal-code-mcp
codex mcp list

codex mcp list で登録を確認し、Codexの新しいセッションで /mcp を開くと、接続状態を確認できます。Codexの公式設定ガイド

Codexのデスクトップアプリでは、設定の「MCP servers」でSTDIOサーバーを追加し、下のJSON例と同じコマンド・引数を指定する方法もあります。

Claude Desktop / Cursor

次のファイルに設定します。

• Claude Desktop（Windows） %APPDATA%/Claude/claude_desktop_config.json

• Claude Desktop（macOS） ~/Library/Application Support/Claude/claude_desktop_config.json

• Cursor .cursor/mcp.json（プロジェクト内）

既に mcpServers がある場合は、その中にサーバーの項目を追加してください。保存後にクライアントを再起動し、ツールが表示されるか確認します。設定ファイルの場所と接続手順

{
  "mcpServers": {
    "jp-postal-code-mcp": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/koizumikento/jp-postal-code-mcp.git@main",
        "jp-postal-code-mcp"
      ]
    }
  }
}

uvx が見つからない場合は、設定のコマンドに実行ファイルの絶対パスを指定してください。

登録後は、チャットで次のように聞けます。

郵便番号100-0001に対応する住所を教えて。

北海道札幌市中央区の「北一条西」に対応する郵便番号を探して。

MCPツール

住所検索は、都道府県名・市区町村名・町域名をつないだ文字列に部分一致します。空白と文字幅の違いを吸収します。next_offset が返ったら、次の検索の offset に指定してください。

CLIで使う

結果は標準出力にUTF-8のJSONで返ります。

uvx --python 3.12 --from git+https://github.com/koizumikento/jp-postal-code-mcp.git@main jp-postal-code-mcp lookup-postal-code --postal-code 100-0001
uvx --python 3.12 --from git+https://github.com/koizumikento/jp-postal-code-mcp.git@main jp-postal-code-mcp search-postal-codes --address "札幌市中央区北一条西" --prefecture "北海道"
uvx --python 3.12 --from git+https://github.com/koizumikento/jp-postal-code-mcp.git@main jp-postal-code-mcp lookup-business-postal-code --postal-code 060-8621

Pythonから呼び出す

リポジトリをクローンし、依存関係を準備します。

git clone https://github.com/koizumikento/jp-postal-code-mcp.git
cd jp-postal-code-mcp
uv sync --locked

次の例を example.py に保存し、クローン先で uv run --locked python example.py を実行します。

import asyncio

from jp_postal_code_mcp import lookup_business_postal_code, search_postal_codes

print(asyncio.run(search_postal_codes(address="札幌市中央区北一条西")))
print(asyncio.run(lookup_business_postal_code(postal_code="060-8621")))

データの更新

MCP・CLI・Pythonは同じローカルキャッシュを使います。町域用と事業所用は、それぞれ初回の利用時に公式CSVを取得します。確認間隔は7日で、期限を過ぎた最初の照会時に更新を確認します。更新に失敗した場合は直前の正常な版を返し、cache.refresh_failed と cache.checked_at で失敗の有無と最後に確認できた日時を判別できます。初回取得に失敗した場合はエラーになります。

すぐに更新したいときは次を実行します。

uvx --python 3.12 --from git+https://github.com/koizumikento/jp-postal-code-mcp.git@main jp-postal-code-mcp refresh
uvx --python 3.12 --from git+https://github.com/koizumikento/jp-postal-code-mcp.git@main jp-postal-code-mcp refresh --dataset business

キャッシュはWindowsでは %LOCALAPPDATA%/jp-postal-code-mcp、その他では $XDG_CACHE_HOME/jp-postal-code-mcp または ~/.cache/jp-postal-code-mcp に保存されます。JP_POSTAL_CODE_CACHE_DIR で保存先を指定できます。

データの出典と利用条件

町域の照会・検索は日本郵便の住所用CSVを使います。結果の data_as_of は配布元が返すアーカイブの更新日時です。更新日時が得られない場合は null になります。住所用CSVの配布ページ・データ説明

個別郵便番号の照会は事業所用CSVを使います。公表を希望しない事業所は収録されません。結果の type_code は 0 が大口事業所、1 が私書箱です。事業所用CSVの配布ページ・データ説明

MIT Licenseはこのリポジトリのコードに適用します。