Nigeria Postcode

ng-postcode-mcp

ナイジェリアの国家デジタル英数字郵便番号システム（NDAPS）向け MCP サーバーです。NIPOST が 2026 年 10 月に開始した、建物単位の郵便番号を扱います。postcode.gov.ng API を通じて、AI アシスタントがオフラインで郵便番号を検証したり、検索、オートコンプリート、場所からの検索を行ったりできるほか、説明された住所から郵便番号を特定できます。

ng-postcode および ng-address-resolver ライブラリを基盤としています。resolve_address を除く同じツールを備えた Node 版は、ng-postcode-mcp として npm で公開されており、npx で実行できます。

独自のコードで郵便番号を検証するには、ライブラリを使用してください。Python 用の ng-postcode、JavaScript 用の ng-postcode-js、Rust 用の ng-postcode、Java 用の ng-postcode-api があります。

ツール

ツール	機能	キーが必要	費用
validate_postcode	オフラインで形式を確認し、正規形式、セグメント、よく似た文字に対する修正候補を返します	いいえ	無料
lookup_postcode	コードが建物に割り当てられていることを確認します	はい	無料
lookup_postcode_details	住所（レベル 2）、建物の用途（レベル 3）などを追加します。NG_POSTCODE_MAX_LEVEL が 2 以上の場合にのみ提供されます	はい	呼び出しごとにクレジットを消費します
autocomplete_postcode	入力途中のコードの次のセグメントを提案します	はい	無料枠
find_postcode_at_location	座標に最も近い建物の郵便番号を返します	はい	無料枠
resolve_address	説明された住所（「Fabian Hotel の裏手、NTA Road 沿い」）または位置ピンを郵便番号に変換します。精度は証拠が裏付ける範囲に限られます	はい。テキストの場合はジオコーダーも必要です	無料枠

lookup_postcode_details を除くすべてのツールは読み取り専用です。lookup_postcode_details はクレジットを消費します。キーの不足やクレジット残高の枯渇など、モデルが対処できるメッセージとしてエラーが返されます。

resolve_address の回答方法

アシスタントが住所を読み取り、目印や地図検索の結果をツールに渡します。サーバー自身がモデルを呼び出すことはありません。回答の精度が証拠を上回ることはありません。

証拠	回答
住所に記載された郵便番号、または建物上の位置ピン	建物コード
住所そのものが示す目印	建物コード、中程度の信頼度
目印の近くの建物（「裏手」「向かい」など）	エリアコードと、ユーザーへの質問
通りのみ	地区コード、低い信頼度
町のみ、または何も見つからない場合	コードなし。ユーザーへの質問

テキストだけで建物を特定できることはまれです。建物を正確に特定する必要がある場合は、ユーザーに位置ピンを求めてください。このツールはリリース前のもので、稼働中の API を使用しますが、実際の住所に対する精度は未測定です。

インストール

あらゆる MCP クライアントで動作します。サーバーは stdio 経由で実行されます。

設定	値
コマンド	uvx
引数	ng-postcode-mcp
環境変数	NG_POSTCODE_API_KEY（validate_postcode では任意）

uv がインストールされている必要があります。NIPOST 開発者ダッシュボードから API キーを取得してください。

ほとんどのクライアントでは、MCP 設定に次のエントリーを追加します。

{
  "mcpServers": {
    "ng-postcode": {
      "command": "uvx",
      "args": ["ng-postcode-mcp"],
      "env": { "NG_POSTCODE_API_KEY": "nipost_live_..." }
    }
  }
}

クライアント	追加方法
Claude Code	claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp
Claude Desktop	上記のエントリーを MCP サーバー設定に追加します
Codex	codex mcp add ng-postcode --env NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp
Cursor	上記のエントリーを .cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）に追加します
VS Code	同じサーバーオブジェクトを .vscode/mcp.json に追加します。ただし、最上位の "mcpServers" ではなく "servers" キーの下に配置してください
その他	stdio サーバーを起動するクライアントであれば、上記のコマンド、引数、環境変数を使用できます

バンドルとして

bundle/ には、Claude Desktop など、.mcpb ファイルをインストールするクライアント向けの MCPB マニフェストが含まれています。uv で公開済みパッケージを実行し、クライアント側の設定で API キーを指定します。リポジトリのルートから npx @anthropic-ai/mcpb pack mcp/bundle ng-postcode.mcpb を実行するとビルドできます。bundle-python/ は、Smithery など、Python バンドルのみを実行するホスト向けの同じバンドルです。サーバーを uvx で起動するため、uv をインストールする必要があります。scripts/smithery_bundle.py は、各ツールの入力スキーマも含む、Smithery が受け付けるコピーをビルドします。

設定

変数	デフォルト	用途
NG_POSTCODE_API_KEY	なし	NIPOST API キーです。環境変数からのみ読み取られ、ツール経由で渡されることはありません。
NG_POSTCODE_MAX_LEVEL	1	ツールが要求できる検索レベルの上限です。レベル 2 以上ではクレジットを消費するため、必要な場合にのみ引き上げてください。
NG_POSTCODE_MAX_PAID_CALLS	25	サーバーの 1 回の実行中に、サーバー自身のキーで実行できる有料検索の回数です。
NG_POSTCODE_BASE_URL	https://api.postcode.gov.ng	ステージング環境など、代替の API ホストです。このマシン上を除き、https である必要があります。
NG_GEOCODER_URL	なし	resolve_address が住所の記述から位置を特定する際に使用する Nominatim サーバーです。これが設定されていない場合、位置を特定できるのは入力された郵便番号と位置ピンのみです。
NG_GEOCODER_CONTACT	なし	User-Agent に含める URL またはメールアドレスです。公開 Nominatim を使用する場合は必須です。
NG_POSTCODE_TRANSPORT	stdio	http にすると、代わりに /mcp でストリーミング可能な HTTP を提供します。
NG_POSTCODE_HOST、NG_POSTCODE_PORT	127.0.0.1、8000	HTTP トランスポートの待ち受け先です。
NG_POSTCODE_ALLOW_SHARED_KEY	未設定	1 にすると、HTTP トランスポートは公開アドレス上でサーバーキーを使用して起動できます。設定されていない場合、この組み合わせは拒否されます。
NG_POSTCODE_ALLOWED_HOSTS	未設定	HTTP トランスポートが応答するホスト名です。mcp.example.com のように、カンマで区切って指定します。公開アドレス上でサーバーキーを使用する場合は必須です。これにより、DNS リバインディングを介してウェブページからキーにアクセスされるのを防ぎます。

公開 Nominatim の https://nominatim.openstreetmap.org で許可されているのは、個人による軽度な利用のみです。ジオコーディングを主な用途とするサービスは、独自のインスタンスを運用する必要があります。地図データ © OpenStreetMap の貢献者。

HTTP と Docker

NG_POSTCODE_TRANSPORT=http uvx ng-postcode-mcp        # http://127.0.0.1:8000/mcp
docker build -t ng-postcode-mcp . && docker run --rm -i ng-postcode-mcp   # from the repository root

HTTP 経由では、呼び出し元は独自の NIPOST キーを X-NIPOST-API-Key ヘッダーで送信でき、そのキーはその呼び出し元のリクエストにのみ使用されます。キーを送信しない呼び出し元には、NG_POSTCODE_API_KEY が設定されている場合、サーバーのキーが使用されます。

ほかのユーザー向けにサーバーをホストする場合は、すべての呼び出し元がキーを持ち込むように NG_POSTCODE_API_KEY を未設定にし、ヘッダーが暗号化されるよう HTTPS 経由で提供してください。呼び出し元はホストにキーを預けることになり、全員でホストのジオコーダーを共有します。このジオコーダーが処理できるのは、1 秒あたり 1 件の検索です。キーがなくても検証は機能します。サーバーキーを設定すると、サーバーにアクセスできるユーザーは誰でもそのクレジットを消費できるため、ループバックに限定するか、独自の認証の背後に置いてください。公開アドレスでキーを設定した場合、NG_POSTCODE_ALLOW_SHARED_KEY=1 を設定し、応答するホストを NG_POSTCODE_ALLOWED_HOSTS に指定しない限り、サーバーは起動を拒否します。NG_POSTCODE_MAX_LEVEL はいずれの場合もすべての呼び出し元の上限を設定し、NG_POSTCODE_MAX_PAID_CALLS はサーバー独自のキーで消費できる上限を設定します。

安全性

• キーは環境変数または X-NIPOST-API-Key ヘッダーから読み取られ、ツールの引数から読み取られることはなく、結果やログに表示されることもありません。
• lookup_postcode は常にレベル 1 で、無料です。有料ツールの lookup_postcode_details は、NG_POSTCODE_MAX_LEVEL を引き上げない限り、モデルから利用できません。
• 有料ツールには読み取り専用や再試行しても安全というマークが付いていないため、読み取り専用ツールを自動的に承認するクライアントでも、支払いが発生する前に確認を求めます。
• 入力ミスのあったコードが、修正されて API にひそかに送信されることはありません。サーバーは候補を返し、モデルにユーザーへの確認を求めます。
• レベル 2 以上では住宅の住所が返されます。ナイジェリアのデータ保護法に基づく個人データとして取り扱ってください。
• resolve_address は検索文字列を、設定したジオコーダーに送信します。サードパーティのジオコーダーを使用する場合、住所のテキストがその事業者と共有されます。

ライセンス

MIT