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.

This is the Node edition of the ng-postcode server. It registers its tools from the same contract as the Python edition, so names, descriptions and schemas are identical. The Python edition also has resolve_address and an HTTP transport.

To validate postcodes in your own code, use the library, ng-postcode-js.

Install

It runs over stdio with npx and needs Node 22.12 or later. Most clients take this entry in their MCP settings:

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

Get an API key from the NIPOST developer dashboard. Validation works without one.

Tools

| Tool | What it does | Needs a key | Cost | | --- | --- | --- | --- | | validate_postcode | Checks structure offline; returns canonical forms, segments and a suggested fix for look-alike characters | No | Free | | lookup_postcode | Confirms a code is assigned to a building | Yes | Free | | lookup_postcode_details | Adds the address (level 2), building use (level 3) and more. Offered only when NG_POSTCODE_MAX_LEVEL is 2 or more | Yes | Uses credits on every call | | autocomplete_postcode | Suggests the next segment of a partly typed code | Yes | Free tier | | find_postcode_at_location | Returns the postcode of the nearest building to a coordinate | Yes | Free tier |

Every tool is read-only except lookup_postcode_details, which spends credits. Errors come back as messages the model can act on.

Configuration

| Variable | Default | Purpose | | --- | --- | --- | | NG_POSTCODE_API_KEY | none | NIPOST API key. Read from the environment only; never passed through tools. | | NG_POSTCODE_MAX_LEVEL | 1 | Highest lookup level tools may request. Levels 2+ consume credits, so raise it deliberately. | | NG_POSTCODE_MAX_PAID_CALLS | 25 | How many paid lookups one run of the server may make with its own key. | | NG_POSTCODE_BASE_URL | https://api.postcode.gov.ng | Alternative API host, such as a staging stack. Must be https, except on this machine. |

Safety

• 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.
• Names and house addresses are withheld from location results unless the cap is 2 or more. Treat them as personal data under the Nigeria Data Protection Act.
• The key is never sent to another host: the client refuses redirects.

License

MIT