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`)