Nigeria Postcode — Claude Code MCP server: features and setup
This MCP server checks Nigerian postcodes and helps agents find codes from coordinates or address details. Use it when a workflow needs to connect a location with a NIPOST postcode.
claude mcp add --env NG_POSTCODE_API_KEY=<NG_POSTCODE_API_KEY> --env NG_POSTCODE_MAX_LEVEL=<NG_POSTCODE_MAX_LEVEL> --env NG_POSTCODE_MAX_PAID_CALLS=<NG_POSTCODE_MAX_PAID_CALLS> --env NG_POSTCODE_BASE_URL=<NG_POSTCODE_BASE_URL> --env NG_GEOCODER_URL=<NG_GEOCODER_URL> --transport stdio mcp -- npx -y ng-postcode-mcpWhat Nigeria Postcode does
Nigeria Postcode gives an agent tools to check postcode structure, find a code assigned to a building, complete a partial code, and search for the nearest building from coordinates. A separate lookup returns more building and address information, and each such call spends credits. The other listed tools are free or have a free tier.
Run the server with Node.js and npx; API lookups need a NIPOST key, while structural validation works without one. Resolving a written address also needs a geocoder. Text descriptions may identify only a district or area rather than the exact building, so use a map pin when building-level precision matters. The maximum lookup level and paid-call cap can be configured through environment variables; raising the lookup level can consume credits.
What it helps with
- validate a Nigerian postcode’s structure without an API key
- find a building’s postcode from a code or coordinates
- complete a partially entered postcode
- turn an address description or map pin into a postcode
Example prompts for the agent
- Check the structure of
1234-5678and suggest a correction if any characters look alike. - Find the postcode for the building at these coordinates.
- Resolve this address to a postcode; ask me for a map pin if the building cannot be identified.
How to install Nigeria Postcode
Platform CLI
claude mcp add --env NG_POSTCODE_API_KEY=<NG_POSTCODE_API_KEY> --env NG_POSTCODE_MAX_LEVEL=<NG_POSTCODE_MAX_LEVEL> --env NG_POSTCODE_MAX_PAID_CALLS=<NG_POSTCODE_MAX_PAID_CALLS> --env NG_POSTCODE_BASE_URL=<NG_POSTCODE_BASE_URL> --env NG_GEOCODER_URL=<NG_GEOCODER_URL> --transport stdio mcp -- npx -y ng-postcode-mcpReplace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
codex mcp add mcp --env NG_POSTCODE_API_KEY=<NG_POSTCODE_API_KEY> --env NG_POSTCODE_MAX_LEVEL=<NG_POSTCODE_MAX_LEVEL> --env NG_POSTCODE_MAX_PAID_CALLS=<NG_POSTCODE_MAX_PAID_CALLS> --env NG_POSTCODE_BASE_URL=<NG_POSTCODE_BASE_URL> --env NG_GEOCODER_URL=<NG_GEOCODER_URL> -- npx -y ng-postcode-mcpReplace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"ng-postcode-mcp"
],
"env": {
"NG_POSTCODE_API_KEY": "<NG_POSTCODE_API_KEY>",
"NG_POSTCODE_MAX_LEVEL": "<NG_POSTCODE_MAX_LEVEL>",
"NG_POSTCODE_MAX_PAID_CALLS": "<NG_POSTCODE_MAX_PAID_CALLS>",
"NG_POSTCODE_BASE_URL": "<NG_POSTCODE_BASE_URL>",
"NG_GEOCODER_URL": "<NG_GEOCODER_URL>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"ng-postcode-mcp"
],
"env": {
"NG_POSTCODE_API_KEY": "<NG_POSTCODE_API_KEY>",
"NG_POSTCODE_MAX_LEVEL": "<NG_POSTCODE_MAX_LEVEL>",
"NG_POSTCODE_MAX_PAID_CALLS": "<NG_POSTCODE_MAX_PAID_CALLS>",
"NG_POSTCODE_BASE_URL": "<NG_POSTCODE_BASE_URL>",
"NG_GEOCODER_URL": "<NG_GEOCODER_URL>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Platform CLI
gemini mcp add -e NG_POSTCODE_API_KEY=<NG_POSTCODE_API_KEY> -e NG_POSTCODE_MAX_LEVEL=<NG_POSTCODE_MAX_LEVEL> -e NG_POSTCODE_MAX_PAID_CALLS=<NG_POSTCODE_MAX_PAID_CALLS> -e NG_POSTCODE_BASE_URL=<NG_POSTCODE_BASE_URL> -e NG_GEOCODER_URL=<NG_GEOCODER_URL> mcp npx -y ng-postcode-mcpReplace <…> with your own values. 6 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Nigeria Postcode
How do I install Nigeria Postcode in Claude Code?
Run claude mcp add ng-postcode -e NG_POSTCODE_API_KEY=<NG_POSTCODE_API_KEY> -- npx -y ng-postcode-mcp. Replace the placeholder with your NIPOST key.
What does Nigeria Postcode do?
It lets an agent validate Nigerian postcode formats, search for building codes, complete partial codes, and resolve location details. The detailed building lookup uses credits.
Does postcode validation require an API key?
Structural validation works without one. Building lookups, autocomplete, and coordinate searches need a NIPOST key; resolving a written address also needs a geocoder.
