Skip to main content
Glama
postcodes-io-mcp

postcodes-io-mcp

by Ankur1911
README.md
# postcodes-io-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server for [Postcodes.io](https://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](https://docs.astral.sh/uv/).

```bash
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:

```json
{
  "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`.

## 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](https://github.com/ideal-postcodes/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

```bash
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.

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