Nigeria Postcode

io.github.Adeniyikayodeev0.2.3更新於 Oct 3, 2026

Validate, look up and resolve addresses to Nigeria's NIPOST digital postcodes (NDAPS).

已驗證STDIO僅桌面Location & Lifestyle Data & Analytics

概覽

AI 產生的概覽

讓助理驗證、查詢、自動補齊與定位奈及利亞 NIPOST 數位郵遞區號，並把描述性地址解析成郵遞區號。

功能: 透過 postcode.gov.ng API 包裝奈及利亞國家數位英數郵遞區號系統（NDAPS）。工具包含 validate_postcode（離線檢查結構，回傳標準格式並提示形近字元的修正）、lookup_postcode（確認編碼已指派，第 2 級回傳地址、第 3 級回傳建築用途）、autocomplete_postcode、find_postcode_at_location，以及 resolve_address，會把描述性地址或位置座標解析成郵遞區號，精確度不超過證據所能支持的程度。所有工具皆為唯讀。
適用情境: 適合助理需要核對或補齊奈及利亞郵遞區號、依座標查找郵遞區號，或把描述模糊的奈及利亞地址轉成郵遞區號的情境。若你經常處理奈及利亞地址，並希望透過官方 API 查詢而非憑空猜測，值得加入。
執行需求: 透過 uvx 以 stdio 在本機執行，需要安裝 uv。需在 NG_POSTCODE_API_KEY 設定來自 NIPOST 開發者後台的 API 金鑰（validate_postcode 可不填）。resolve_address 處理文字時需要 NG_GEOCODER_URL，使用公開 Nominatim 時還需 NG_GEOCODER_CONTACT。NG_POSTCODE_MAX_LEVEL 預設為 1；NG_POSTCODE_BASE_URL 可指向其他主機。

安裝前請注意

第 2 級以上會消耗 NIPOST 額度並回傳住宅地址，README 將其視為奈及利亞資料保護法下的個人資料；請刻意調高 NG_POSTCODE_MAX_LEVEL。resolve_address 會把地址搜尋字串傳送給你設定的地理編碼器，第三方地理編碼器因此會看到這些文字。公開 Nominatim 僅允許輕度個人使用。API 金鑰只從環境變數讀取，不會經由工具傳遞。

安裝

在 SourceWeft 中

開啟儀表板中的 Nigeria Postcode，將其新增到工作區。
為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照儲存庫中的啟動說明。

README

ng-postcode-mcp

MCP server for Nigeria's National Digital Alphanumeric Postcode System (NDAPS), the building-level postcode NIPOST launched in October 2026. It lets AI assistants validate postcodes offline, look them up, autocomplete them and find them by location through the postcode.gov.ng API, and resolve described addresses to postcodes.

Built on the ng-postcode and ng-address-resolver libraries.

Tools

Tool	What it does	Needs a key	Cost
`validate_postcode`	Checks structure offline; returns canonical forms, segments and a suggested fix for look-alike characters	No	Free
`lookup_postcode`	Confirms a code is assigned; level 2 adds the address, level 3 building use	Yes	Level 1 free, 2+ uses credits
`autocomplete_postcode`	Suggests the next segment of a partly typed code	Yes	Free tier
`find_postcode_at_location`	Returns the postcode of the nearest building to a coordinate	Yes	Free tier
`resolve_address`	Turns a described address ("back of Fabian Hotel, off NTA Road") or a location pin into a postcode, only as precisely as the evidence allows	Yes, plus a geocoder for text	Free tier

All tools are read-only. Errors come back as messages the model can act on, such as a missing key or an exhausted credit balance.

How `resolve_address` answers

The assistant reads the address and passes its landmarks and map searches to the tool; the server makes no model calls of its own. The answer is never more precise than its evidence:

Evidence	Answer
A postcode written in the address, or a location pin on a building	Building code
A landmark the address is	Building code, medium confidence
A building near a landmark ("behind", "opposite")	Area code, plus a question for the user
A street only	District code, low confidence
A town only, or nothing found	No code, plus a question

Text alone rarely identifies a building, so ask users for a location pin when the exact building matters. This tool is pre-release: it works against the live API, but its accuracy on real addresses is unmeasured.

Install

Works with any MCP client. The server runs over stdio:

It needs uv installed. Get an API key from the NIPOST developer dashboard.

Most clients take this entry in their MCP settings:

json

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

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

Client	How to add it
Claude Code	`claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp`
Claude Desktop	The entry above, in its MCP server settings
Codex	`codex mcp add ng-postcode --env NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp`
Cursor	The entry above, in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
VS Code	The same server object in `.vscode/mcp.json`, under a top-level `"servers"` key instead of `"mcpServers"`
Others	Any client that launches stdio servers: use the command, arguments and environment above

Configuration

Variable	Default	Purpose
`NG_POSTCODE_API_KEY`	none	NIPOST API key. Read from the environment only; never passed through tools.
`NG_POSTCODE_MAX_LEVEL`	`1`	Highest lookup level tools may request. Levels 2+ consume credits, so raise it deliberately.
`NG_POSTCODE_BASE_URL`	`https://api.postcode.gov.ng`	Alternative API host, such as a staging stack.
`NG_GEOCODER_URL`	none	A Nominatim server `resolve_address` uses to place described addresses. Without it, only typed postcodes and location pins resolve.
`NG_GEOCODER_CONTACT`	none	A URL or email sent in the User-Agent. Required for the public Nominatim.

The public Nominatim at https://nominatim.openstreetmap.org allows light personal use only; a service whose main job is geocoding must run its own instance. Map data © OpenStreetMap contributors.

Safety

Lookups default to level 1, which is free. A model cannot spend credits unless you raise NG_POSTCODE_MAX_LEVEL.
A mistyped code is never corrected and sent to the API silently. The server returns the suggestion and asks the model to confirm it with the user.
Levels 2 and up return house addresses. Treat them as personal data under the Nigeria Data Protection Act.
resolve_address sends the search strings to the geocoder you configure. With a third-party geocoder, that shares address text with it.

License

MIT

來源：mcp/README.md，提交 900bf78

工具

工具後設資料尚未被收錄。

版本歷史

v0.2.3最新Oct 3, 2026

Setting	Value
Command	`uvx`
Arguments	`ng-postcode-mcp`
Environment	`NG_POSTCODE_API_KEY` (optional for `validate_postcode`)