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 and look them up, autocomplete them and find them by location through the postcode.gov.ng API.

Built on the ng-postcode library.

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.

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

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.

License

MIT