Skip to main content
Glama
postcodes-io-mcp

postcodes-io-mcp

by Ankur1911

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 transport

Add 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

lookup_postcodes

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 terminated with year and month; unknown ones under not_found; malformed ones under invalid_format (checked locally, no request sent). detail="full" returns every field.

find_postcodes

Complete or search a partial postcode (SW1A 2, EH1), with local authority, ward and coordinates.

nearest_postcodes

Postcodes closest to a postcode or to a latitude/longitude, with distance in metres. This is the reverse-geocoding tool.

distance_between

Great-circle distance in km and miles between two locations, each a postcode or a lat,lon pair. For two postcodes it also reports whether they share a local authority, constituency and country.

outcode_info

Centre point and the authorities, wards, parishes and constituencies an outcode (SW1A, M1) spans; optionally the nearest neighbouring outcodes.

find_places

Great Britain place names (Ordnance Survey data) with type, outcode, district, region, country and coordinates.

scottish_postcode

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

POSTCODES_IO_BASE_URL

https://api.postcodes.io

API root (for a self-hosted instance or proxy)

POSTCODES_IO_TIMEOUT

20

Request timeout in seconds

POSTCODES_IO_RETRIES

2

Retries on HTTP 429, 502, 503, 504 and timeouts

POSTCODES_IO_MAX_CHARS

20000

Responses longer than this are cut with a notice

MCP_TRANSPORT

stdio

stdio or streamable-http

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_postcodes have 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_between is a straight-line distance, not a road or travel distance.

  • find_places covers 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 pytest

Tests 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 tools
distance_betweenA
Read-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_placesA
Read-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_postcodesA
Read-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_postcodesA
Read-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_postcodesA
Read-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_infoA
Read-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_postcodeA
Read-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

    A4.1/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Global 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.
      4
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      UK 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides 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 PyPI
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables UK postcode lookups including geographic details, nearest postcodes, validation, and random postcode generation via the free postcodes.io API.
      86 npm
      MIT