Nigeria Postcode

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. A Node edition with the same tools, apart from resolve_address, is on npm as ng-postcode-mcp and runs with npx.

To validate postcodes in your own code, use the libraries: ng-postcode for Python, ng-postcode-js for JavaScript, ng-postcode for Rust, and ng-postcode-api for Java.

Tools

Every tool is read-only except lookup_postcode_details, which spends credits. 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:

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:

{

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

As a bundle

bundle/ holds an MCPB manifest for clients that install .mcpb files, such as Claude Desktop. It runs the published package with uv and asks for the API key in the client's own settings. Build it with npx @anthropic-ai/mcpb pack mcp/bundle ng-postcode.mcpb from the repository root. bundle-python/ is the same bundle for hosts that only run Python bundles, such as Smithery; it starts the server with uvx, so uv must be installed. scripts/smithery_bundle.py builds the copy Smithery accepts, which also carries each tool's input schema.

Configuration

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.

HTTP and 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

Over HTTP a caller can send its own NIPOST key in the X-NIPOST-API-Key header, and that key is used for that caller's requests only. A caller that sends none uses the server's key, if NG_POSTCODE_API_KEY is set.

To host the server for other people, leave NG_POSTCODE_API_KEY unset so every caller brings a key, and serve it over HTTPS so the header is encrypted. Callers are trusting the host with their key, and all of them share the host's geocoder, which answers one search a second. Validation still works without any key. If you do set a server key, anyone who can reach the server spends its credits, so keep it on loopback or behind your own authentication. The server refuses to start with a key on a public address unless you set NG_POSTCODE_ALLOW_SHARED_KEY=1 and name the hosts it answers to in NG_POSTCODE_ALLOWED_HOSTS. NG_POSTCODE_MAX_LEVEL caps every caller either way, and NG_POSTCODE_MAX_PAID_CALLS caps what the server's own key can spend.

Safety

• The key is read from the environment or the X-NIPOST-API-Key header, never from tool arguments, and never appears in results or logs.
• lookup_postcode is always level 1, which is free. The paid tool, lookup_postcode_details, does not exist for the model unless you raise NG_POSTCODE_MAX_LEVEL.
• The paid tool is not marked read-only or safe to retry, so a client that approves read-only tools on its own will still ask before spending.
• 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