postcodes-io-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@postcodes-io-mcp Look up SW1A 1AA and M1 1AE — what council areas are they in?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
postcodes-io-mcp
A Model Context Protocol server for Postcodes.io, the free open-data API for UK postcodes (built on Ordnance Survey and ONS data). It needs no API key and is read-only.
The tools are shaped around common jobs rather than one tool per endpoint: bulk lookups with terminated or invalid postcodes sorted into separate buckets, reverse geocoding with distances, a two-location distance check that also compares administrative areas, and trimmed responses with the ONS/GSS codes grouped in one place.
Setup
Requires Python 3.12+ and uv.
git clone https://github.com/Ankur1911/postcodes-io-mcp && cd postcodes-io-mcp
uv sync
uv run postcodes-io-mcp # stdio transportAdd it to any MCP client that launches stdio servers:
{
"mcpServers": {
"postcodes-io": {
"command": "uv",
"args": ["run", "--directory", "/path/to/postcodes-io-mcp", "postcodes-io-mcp"]
}
}
}For HTTP instead of stdio: MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 uv run postcodes-io-mcp.
Related MCP server: Postio
Tools
All tools are read-only.
Tool | What it returns |
| 1 to 100 postcodes in one call (one bulk request, any spacing or case). Per match: country, region, local authority, county, ward, parish, parliamentary constituency (2024 boundaries), Senedd constituency, coordinates, OS grid reference, LSOA/MSOA, NUTS, police force area, ICB, urban/rural class, deprivation rank and the matching GSS codes. Postcodes that are no longer live are returned under |
| Complete or search a partial postcode ( |
| Postcodes closest to a postcode or to a latitude/longitude, with distance in metres. This is the reverse-geocoding tool. |
| Great-circle distance in km and miles between two locations, each a postcode or a |
| Centre point and the authorities, wards, parishes and constituencies an outcode ( |
| Great Britain place names (Ordnance Survey data) with type, outcode, district, region, country and coordinates. |
| Scotland-only data: council area, Scottish Parliament constituency and region, health board, integration authority, data zone, intermediate zone, locality and settlement. |
Configuration
All optional environment variables:
Variable | Default | Meaning |
|
| API root (for a self-hosted instance or proxy) |
|
| Request timeout in seconds |
|
| Retries on HTTP 429, 502, 503, 504 and timeouts |
|
| Responses longer than this are cut with a notice |
|
|
|
Limits
UK postcodes only. Northern Ireland postcodes resolve, but some area fields (region, MSOA) are empty there.
The public instance is free and rate limited. The server retries politely but does not queue requests; for heavy use run your own postcodes.io instance and set
POSTCODES_IO_BASE_URL.Bulk lookups are capped at 100 postcodes per call. At most 10 unmatched postcodes per call are checked against the terminated-postcodes dataset; the rest are listed as
not_found.Reverse geocoding and
nearest_postcodeshave a 2000 m maximum radius. A postcode is a delivery area, not a building, so the nearest postcode is an approximation of an address.distance_betweenis a straight-line distance, not a road or travel distance.find_placescovers Great Britain place names, not Northern Ireland.Data freshness follows the upstream ONS and Ordnance Survey releases; very new postcodes may be missing.
Development
uv sync
uv run pytestTests mock all HTTP traffic with respx; no network access is needed.
Licence
MIT. Author: Ankur Kapuriya. Not affiliated with or endorsed by Postcodes.io, Ideal Postcodes, Ordnance Survey or the Office for National Statistics. Postcodes.io data contains Ordnance Survey and ONS data under the Open Government Licence; check their terms before redistributing results.
Available Tools
7 toolsdistance_betweenARead-onlyIdempotent
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.
Inputs: origin (required), destination (required).
find_placesARead-onlyIdempotent
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.
Inputs: query (required), limit.
find_postcodesARead-onlyIdempotent
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.
Inputs: query (required), limit.
lookup_postcodesARead-onlyIdempotent
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.
Inputs: postcodes (required), detail.
nearest_postcodesARead-onlyIdempotent
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.
Inputs: limit, latitude, postcode, radius_m, +1 more.
outcode_infoARead-onlyIdempotent
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.
Inputs: outcode (required), nearby.
scottish_postcodeARead-onlyIdempotent
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.
Inputs: postcode (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
UK postcode lookup, nearest postcodes, autocomplete and distance (OS open data)
UK postcode lookup, street-level crime, flood warnings, grid carbon intensity, bank holidays
Access comprehensive UK postcode information effortlessly with our geocoding services. Whether you
Unofficial Postcodes MCP — wraps postcodes.io UK postcode API (free, no auth)
Related MCP Servers
- AlicenseAqualityDmaintenanceGlobal postal code lookups, validation, and city search for 240+ countries with timezone, admin region, and elevation metadata. Sub-10ms responses at $0.000028/query with 1,000 free queries on signup.41MIT
- AlicenseNot gradedqualityBmaintenanceUK address (Royal Mail PAF), email, and phone (live HLR carrier) validation via the Postio API. Six tools: address search, postcode lookup, UDPRN, email validate, phone validate, and a health probe.MIT

Acuris Geo MCP Serverofficial
AlicenseNot gradedqualityCmaintenanceProvides address validation and geocoding for 240+ countries, including UK Royal Mail PAF and US/Canada census enrichment. Enables batch validation, forward/reverse geocoding, UK postcode expansion, and automatic refunds for failed lookups.61 PyPIMIT- AlicenseNot gradedqualityCmaintenanceEnables UK postcode lookups including geographic details, nearest postcodes, validation, and random postcode generation via the free postcodes.io API.86 npmMIT