Nigeria Postcode

ng-postcode-mcp

用于尼日利亚国家数字字母数字邮政编码系统（NDAPS）的 MCP 服务。该系统是 NIPOST 于 2026 年 10 月推出的楼宇级邮政编码系统。它可通过 postcode.gov.ng API，让 AI 助手离线验证邮政编码、查询和自动补全邮政编码、按位置查找邮政编码，并将文字描述的地址解析为邮政编码。

基于 ng-postcode 和 ng-address-resolver 库构建。npm 上还提供了具备相同工具的 Node 版本（不含 resolve_address），名为 ng-postcode-mcp，可通过 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（会消耗额度）外，所有工具均为只读。错误会以模型可采取行动的消息形式返回，例如缺少密钥或额度已用尽。

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 中添加相同的服务对象，使用顶层 "servers" 键而非 "mcpServers"
其他	任何可启动 stdio 服务的客户端：使用上面的命令、参数和环境变量

作为套件

bundle/ 包含适用于安装 .mcpb 文件的客户端（例如 Claude Desktop）的 MCPB 清单。它通过 uv 运行已发布的软件包，并要求在客户端自己的设置中填写 API 密钥。请在仓库根目录运行 npx @anthropic-ai/mcpb pack mcp/bundle ng-postcode.mcpb 进行构建。bundle-python/ 是面向仅支持 Python 套件的宿主（例如 Smithery）的相同套件；它使用 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	服务单次运行使用自身密钥可进行的付费查询次数。
NG_POSTCODE_BASE_URL	https://api.postcode.gov.ng	替代 API 主机，例如预发布环境。必须使用 https，但本机除外。
NG_GEOCODER_URL	无	resolve_address 用于定位描述性地址的 Nominatim 服务。未设置时，只能解析输入的邮政编码和位置图钉。
NG_GEOCODER_CONTACT	无	在 User-Agent 中发送的网址或电子邮件。使用公共 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，调用方可以在 X-NIPOST-API-Key 请求头中发送自己的 NIPOST 密钥，该密钥仅用于该调用方的请求。未发送密钥的调用方会使用服务端的密钥（前提是已设置 NG_POSTCODE_API_KEY）。

如果要为他人托管此服务，请不要设置 NG_POSTCODE_API_KEY，这样每位调用方都需提供自己的密钥；同时应通过 HTTPS 提供服务，以加密请求头。调用方需要信任主机并向其提供密钥，而且所有调用方共用主机的地理编码器，该编码器每秒处理一次搜索。即使没有任何密钥，验证仍然有效。如果设置了服务端密钥，任何能访问该服务的用户都可以消耗该密钥的额度，因此请将服务限制在回环地址上，或放在你自己的身份验证机制之后。如果在公网地址上配置密钥，服务端将拒绝启动，除非设置 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 级，且免费。除非提高 NG_POSTCODE_MAX_LEVEL，否则模型无法使用付费工具 lookup_postcode_details。
• 该付费工具不会标记为只读或可安全重试，因此，即使客户端会自动批准只读工具，也仍会在产生费用前询问用户。
• 对于拼写错误的邮编，系统绝不会擅自更正后静默发送给 API。服务端会返回建议，并要求模型向用户确认。
• 第 2 级及以上会返回住宅地址。根据《尼日利亚数据保护法》，应将这些信息视为个人数据。
• resolve_address 会将搜索字符串发送给你配置的地理编码器。使用第三方地理编码器时，这些地址文本也会与其共享。

许可证

MIT