postcodes-io-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MCP_HOST | No | Host to bind when using the streamable-http transport (e.g. 127.0.0.1). | |
| MCP_PORT | No | Port to bind when using the streamable-http transport (e.g. 8000). | |
| MCP_TRANSPORT | No | Transport to use: stdio or streamable-http. Default: stdio | stdio |
| POSTCODES_IO_RETRIES | No | Retries on HTTP 429, 502, 503, 504 and timeouts. Default: 2 | 2 |
| POSTCODES_IO_TIMEOUT | No | Request timeout in seconds. Default: 20 | 20 |
| POSTCODES_IO_BASE_URL | No | API root (for a self-hosted instance or proxy). Default: https://api.postcodes.io | https://api.postcodes.io |
| POSTCODES_IO_MAX_CHARS | No | Responses longer than this are cut with a notice. Default: 20000 | 20000 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
UK postcode data from Postcodes.io (Ordnance Survey and ONS open data). Use lookup_postcodes to turn postcodes into coordinates, local authority, ward, constituency and census area codes (many at once). Use nearest_postcodes to reverse-geocode a point, distance_between to compare two locations, find_postcodes to complete a partial postcode, and find_places to go from a place name to coordinates. UK only. Read-only, no credentials.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| lookup_postcodesA | Look up 1 to 100 UK postcodes in one call (any spacing or case). Each match returns country, region, local authority (admin_district), county, ward, parish, parliamentary constituency (2024 boundaries), Senedd constituency for Wales, latitude/longitude, OS eastings/northings, LSOA/MSOA, NUTS, police force area, ICB, urban/rural class, deprivation rank and the matching ONS/GSS codes. Postcodes that are no longer live come back under 'terminated' with the year and month; unknown ones under 'not_found'; badly formatted ones under 'invalid_format' without spending an API call. Use detail='full' for every field. |
| find_postcodesA | Complete or search a partial postcode, e.g. 'SW1A 2', 'EH1 1' or 'M1'. Returns matching postcodes with local authority, ward, region and coordinates. Use it when you only have a prefix or a postcode with a typo. For full details of a known postcode use lookup_postcodes. |
| nearest_postcodesA | Postcodes closest to a point, with distance in metres. Pass either a postcode (the nearest-neighbour lookup) or a latitude and longitude (reverse geocoding). The nearest result is often the building the point sits in, so this is the way to turn GPS coordinates into a postcode and local authority. Radius is capped at 2000 m by the service. |
| distance_betweenA | Straight-line (great-circle) distance in km and miles between two UK locations. Each end is a postcode or a 'latitude,longitude' pair. For two postcodes it also says whether they share a local authority, parliamentary constituency and country. Not a driving or travel distance. |
| outcode_infoA | Information about an outcode (the first half of a postcode, such as 'SW1A' or 'M1'): its centre point and the local authorities, wards, parishes, counties, countries and constituencies it spans. Set nearby to also list the closest neighbouring outcodes. |
| find_placesA | Search Great Britain place names (cities, towns, villages, hamlets; Ordnance Survey data) and get the type, outcode, county or unitary authority, district, region, country and coordinates. Names can repeat (there are several Leeds), so check the district and region. Use it to get from a place name to coordinates or an outcode. |
| scottish_postcodeA | Scotland-specific data for a Scottish postcode: council area, electoral ward, Scottish Parliament constituency and region, health board, integration authority, data zone and intermediate zone, locality, settlement, island and travel-to-work area. Not available for other UK nations; use lookup_postcodes for those. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 7 tools
Each tool has a clearly distinct role: full postcode lookup, partial/typo completion, nearest/reverse geocoding, distance calculation, outcode metadata, place-name search, and Scotland-specific enrichment. The descriptions explicitly route users between similar-sounding tools, such as lookup_postcodes versus find_postcodes and scottish_postcode. Overlap is minimal and intentional.
The set mixes several naming conventions: verb_noun (lookup_postcodes, find_postcodes, find_places), adjective_noun (nearest_postcodes, scottish_postcode), noun_info (outcode_info), and a prepositional phrase (distance_between). The names are still readable and mostly intuitive, but the pattern is not consistent enough for a higher score.
Seven tools is well-scoped for a postcode/geospatial API and each tool covers a distinct query pattern. There is no obvious padding or missing high-level operation that would require splitting or merging tools.
The surface covers the core postcode workflows: lookup, validation via invalid handling, partial search, reverse geocoding, distance, outcode context, and place lookup. Minor gaps remain, such as place-name search being limited to Great Britain rather than the whole UK and no bulk reverse/distance matrix operations, but agents can work around these.