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.

Install

It runs over stdio with npx and needs Node 20.10 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; level 2 adds the address, level 3 building use	Yes	Level 1 free, 2+ uses credits
`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

All tools are read-only. 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_BASE_URL`	`https://api.postcode.gov.ng`	Alternative API host, such as a staging stack.

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