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: its NIPOST steps have not yet been run against the live API.

Install

Requires uv. Get an API key from the NIPOST developer dashboard; validate_postcode works without one.

Claude Code

claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp

Claude Desktop, Cursor and other clients that use an mcpServers config:

{
  "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.

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