Nigeria Postcode

io.github.Adeniyikayodeev0.2.3Updated Oct 3, 2026

Validate, look up and resolve addresses to Nigeria's NIPOST digital postcodes (NDAPS).

VerifiedSTDIODesktop onlyData & AnalyticsLocation & Lifestyle

Overview

AI-generated overview

Lets an assistant validate, look up, autocomplete and locate Nigeria's NIPOST digital postcodes, and resolve described addresses to codes.

What it does
Wraps Nigeria's National Digital Alphanumeric Postcode System (NDAPS) through the postcode.gov.ng API. Tools include validate_postcode (offline structure check with canonical forms and fixes for look-alike characters), lookup_postcode (confirms a code is assigned, with address at level 2 and building use at level 3), autocomplete_postcode, find_postcode_at_location, and resolve_address, which turns a described address or location pin into a postcode only as precisely as the evidence allows. All tools are read-only.
When to use it
Useful when an assistant must check or complete Nigerian postcodes, find the code for a coordinate, or turn a loosely described Nigerian address into a postcode. Worth adding if you work with Nigerian addresses and want the lookup done through the official API rather than guesswork.
Requirements
Runs locally over stdio via uvx, so uv must be installed. An API key from the NIPOST developer dashboard is set in NG_POSTCODE_API_KEY (optional for validate_postcode). resolve_address for text needs NG_GEOCODER_URL and, for the public Nominatim, NG_GEOCODER_CONTACT. NG_POSTCODE_MAX_LEVEL defaults to 1; NG_POSTCODE_BASE_URL can point at another host.
Before you install
Levels 2 and up consume NIPOST credits and return house addresses, which the README treats as personal data under the Nigeria Data Protection Act; raise NG_POSTCODE_MAX_LEVEL deliberately. resolve_address sends address search strings to the geocoder you configure, so a third-party geocoder sees that text. The public Nominatim allows light personal use only. The API key is read from the environment and never passed through tools.

Installation

In SourceWeft

  1. Open Nigeria Postcode in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

ToolWhat it doesNeeds a keyCost
validate_postcodeChecks structure offline; returns canonical forms, segments and a suggested fix for look-alike charactersNoFree
lookup_postcodeConfirms a code is assigned; level 2 adds the address, level 3 building useYesLevel 1 free, 2+ uses credits
autocomplete_postcodeSuggests the next segment of a partly typed codeYesFree tier
find_postcode_at_locationReturns the postcode of the nearest building to a coordinateYesFree tier
resolve_addressTurns a described address ("back of Fabian Hotel, off NTA Road") or a location pin into a postcode, only as precisely as the evidence allowsYes, plus a geocoder for textFree tier

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:

EvidenceAnswer
A postcode written in the address, or a location pin on a buildingBuilding code
A landmark the address isBuilding code, medium confidence
A building near a landmark ("behind", "opposite")Area code, plus a question for the user
A street onlyDistrict code, low confidence
A town only, or nothing foundNo code, plus a question

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:

SettingValue
Commanduvx
Argumentsng-postcode-mcp
EnvironmentNG_POSTCODE_API_KEY (optional for validate_postcode)

It needs uv installed. Get an API key from the NIPOST developer dashboard.

Most clients take this entry in their MCP settings:

json
{  "mcpServers": {    "ng-postcode": {      "command": "uvx",      "args": ["ng-postcode-mcp"],      "env": { "NG_POSTCODE_API_KEY": "nipost_live_..." }    }  }}
ClientHow to add it
Claude Codeclaude mcp add ng-postcode -e NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp
Claude DesktopThe entry above, in its MCP server settings
Codexcodex mcp add ng-postcode --env NG_POSTCODE_API_KEY=nipost_live_... -- uvx ng-postcode-mcp
CursorThe entry above, in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
VS CodeThe same server object in .vscode/mcp.json, under a top-level "servers" key instead of "mcpServers"
OthersAny client that launches stdio servers: use the command, arguments and environment above

Configuration

VariableDefaultPurpose
NG_POSTCODE_API_KEYnoneNIPOST API key. Read from the environment only; never passed through tools.
NG_POSTCODE_MAX_LEVEL1Highest lookup level tools may request. Levels 2+ consume credits, so raise it deliberately.
NG_POSTCODE_BASE_URLhttps://api.postcode.gov.ngAlternative API host, such as a staging stack.
NG_GEOCODER_URLnoneA Nominatim server resolve_address uses to place described addresses. Without it, only typed postcodes and location pins resolve.
NG_GEOCODER_CONTACTnoneA URL or email sent in the User-Agent. Required for the public Nominatim.

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

Source: mcp/README.md at commit 900bf78

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.3LatestOct 3, 2026