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

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:

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_..." }
    }
  }
}

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. NG_POSTCODE_MAX_LEVEL caps every caller either way.

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.
• 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