OpenPostcodes MCP server

OpenPostcodes is also available as a Model Context Protocol (MCP) server. AI assistants such as Claude, ChatGPT, Cursor and VS Code can use it to look up UK postcodes, compare them and browse areas, districts and sectors: where a postcode is, the council, ward and constituency it is in, what is nearby, and who supplies its utilities. It only reads the data (but for sending feedback, when you agree), needs no key, account or sign-in, and serves the same data, under the same licences, as the rest of this site.

Server URL

https://openpostcodes.uk/mcp

Transport

Streamable HTTP

Authentication

None

Version

1.0.0

Connect

Every client needs only the server URL. When a client asks how to authenticate, choose no authentication.

Claude (claude.ai, Desktop and mobile)

Add OpenPostcodes to Claude opens the Add custom connector dialog with the name and URL filled in; check them and click Add.

To add it by hand, go to Customize, then Connectors, and click Add custom connector. Enter the name OpenPostcodes and the URL https://openpostcodes.uk/mcp, and if the dialog asks about authentication, choose No sign-in. The connector then works in the Claude apps on desktop and mobile too. On Team and Enterprise plans an Owner adds it for everyone under Organization settings, Connectors, Add, Custom, Web (or with the prefilled admin link).

Claude Code

claude mcp add --transport http openpostcodes https://openpostcodes.uk/mcp

Add --scope project to share it through the project's .mcp.json, which looks like this:

{
  "mcpServers": {
    "openpostcodes": {
      "type": "http",
      "url": "https://openpostcodes.uk/mcp"
    }
  }
}

Prompts appear as slash commands such as /mcp__openpostcodes__postcode_report, and resources can be attached with @openpostcodes:.

ChatGPT

Turn on developer mode under Settings, Security and login, Developer mode. Then go to chatgpt.com/plugins, select the plus button, give it a name and description, enter https://openpostcodes.uk/mcp as the connection URL with no authentication, and create it. The search and fetch tools follow OpenAI's contract, so deep research can use them and cite openpostcodes.uk pages.

Cursor

Add to Cursor, or put this in ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "openpostcodes": {
      "url": "https://openpostcodes.uk/mcp"
    }
  }
}

VS Code

Install in VS Code, or add it to .vscode/mcp.json (the top-level key is servers):

{
  "servers": {
    "openpostcodes": {
      "type": "http",
      "url": "https://openpostcodes.uk/mcp"
    }
  }
}

From a terminal:

code --add-mcp '{"name":"openpostcodes","type":"http","url":"https://openpostcodes.uk/mcp"}'

OpenAI Codex

codex mcp add openpostcodes --url https://openpostcodes.uk/mcp

or in ~/.codex/config.toml:

[mcp_servers.openpostcodes]
url = "https://openpostcodes.uk/mcp"

Codex uses tools only, not prompts or resources.

Gemini CLI

gemini mcp add --transport http openpostcodes https://openpostcodes.uk/mcp

or in ~/.gemini/settings.json, where httpUrl (not url) selects Streamable HTTP:

{
  "mcpServers": {
    "openpostcodes": {
      "httpUrl": "https://openpostcodes.uk/mcp"
    }
  }
}

Windsurf (Devin Desktop)

Add it to mcp_config.json, which is at ~/.config/devin/mcp_config.json on macOS and Linux and %APPDATA%\devin\mcp_config.json on Windows:

{
  "mcpServers": {
    "openpostcodes": {
      "serverUrl": "https://openpostcodes.uk/mcp"
    }
  }
}

Zed

Use Settings, AI, MCP Servers, Add Server, Add Remote Server, or add it to your settings file:

{
  "context_servers": {
    "openpostcodes": {
      "url": "https://openpostcodes.uk/mcp"
    }
  }
}

Zed uses tools and prompts.

Goose

Run goose configure and add a remote extension (Streamable HTTP), or add it to ~/.config/goose/config.yaml:

extensions:
  openpostcodes:
    name: OpenPostcodes
    type: streamable_http
    uri: https://openpostcodes.uk/mcp
    enabled: true
    timeout: 300

For one session only:

goose session --with-streamable-http-extension "https://openpostcodes.uk/mcp"

MCP Inspector

To explore the server by hand, start the Inspector, choose Streamable HTTP and paste the URL:

npx @modelcontextprotocol/inspector

or use its command line (add --protocol-era modern to try the 2026-07-28 protocol):

npx @modelcontextprotocol/inspector --cli --transport http --server-url https://openpostcodes.uk/mcp --method tools/list

Clients that only run local servers

A client that can only start local (stdio) servers can reach OpenPostcodes through mcp-remote:

{
  "mcpServers": {
    "openpostcodes": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://openpostcodes.uk/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

Things to ask

• Which council, ward and constituency is EX11 1RE in?
• How far is SW1A 1AA from EH1 1BB, and what areas do they share?
• What are the nearest railway station, GP and pharmacy to M1 1AE?
• Who runs the electricity network and the water supply at CF10 1EP, and how good is the broadband?
• List the postcodes in the EX11 1 sector.
• How deprived is the area around G1 1XW, and what does the rank mean?

Tools

10 tools, all read-only except send_feedback, which sends a note to the people who run OpenPostcodes (see feedback). Each returns structured data, repeated as JSON text, with openpostcodes.uk links to cite.

Prompts

Prompts are ready-made research tasks that your client may offer as commands. Each one asks the assistant to use the tools above, cite its sources and list what it could not check.

Resources

Resources are documents a client can attach to a conversation. Their addresses are the same https URLs a browser opens, and reading one returns what the site serves.

Reference documents

Records by identifier

Try it with curl

The server is stateless, so every request stands on its own. A modern (2026-07-28) request carries its protocol version and client capabilities in params._meta and repeats the version, method and tool name in headers. A legacy client starts with initialize; later requests name the agreed version in the MCP-Protocol-Version header and need no session id, because none is ever issued.

Modern (2026-07-28): ask the server what it supports

curl -s https://openpostcodes.uk/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: server/discover' \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"}}}}'

Modern (2026-07-28): call get_postcode for EX11 1RE

curl -s https://openpostcodes.uk/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: get_postcode' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_postcode","arguments":{"postcode":"EX11 1RE"},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"}}}}'

Legacy (2025-11-25): the initialize handshake

curl -s https://openpostcodes.uk/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Legacy (2025-11-25): list the tools (no session to carry over)

curl -s https://openpostcodes.uk/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Each of these answers is a single JSON response.

Limits and fair use

• Lists come a page at a time. Pass the next_cursor from one page as cursor to get the next. A sector's postcodes, a district's sectors and an area's districts each stop after 1,000 rows (the longest, a sector, holds about 400), and lookup_postcodes takes at most 100 postcodes a call; narrow the query to go further.
• Totals stop counting at 1,000, which no list here reaches, and total_is_capped says so.
• Each database query may run for 8 seconds, and each tool call for 20 seconds in all. A query that runs out of time returns a message saying what to do.
• A tool result is at most 60,000 characters, a resource at most 1 MiB, and a request body at most 64 KiB. A legacy batch holds at most 10 messages.
• Please keep automated use gentle, a few requests a second at most. Heavy traffic may be rate limited.
• Please cache what you fetch. For every postcode at once, use the ONS Postcode Directory itself rather than paging through the MCP server.

Data caveats

• Live postcodes only: terminated postcodes are left out, so a postcode that is not found may have been retired.
• Coordinates are the centroid of the postcode, not any one building. The Channel Islands, the Isle of Man and GIR 0AA have none, so their location fields are null.
• Deprivation (classification.imd) is a rank on each country's own index (England's IMD, Scotland's SIMD, Wales's WIMD, Northern Ireland's NIMDM), 1 being the most deprived. Ranks do not compare across countries.
• Nearest places are straight-line distances from the centroid, and coverage varies: schools for England and Scotland only, hospitals and GPs for England and Northern Ireland only (its hospitals a hand-compiled list of major sites).
• Boundaries are approximate (a 2021 Voronoi diagram of address points), Great Britain only, missing for postcodes introduced since, and not legal boundaries.
• Electricity, water and sewerage companies come from supply-area maps: approximate, not a record of supply, and new-build connections in particular may differ.
• Broadband figures are Ofcom's percentages of premises, for Great Britain and Northern Ireland, and null where Ofcom has no record for the postcode.
• sun (sunrise, solar noon, sunset) and magnetic_declination are for today and change daily; declination is null outside the World Magnetic Model's 2025 to 2030 window.
• Northern Ireland postcodes (BT) are under the Northern Ireland End User Licence: commercial re-use may need a licence from Land & Property Services.

The data guide explains them in full, with how postcodes and the levels above them are identified, and status.json says how current each part is.

Feedback

send_feedback lets an assistant send the people who run OpenPostcodes a short note about these tools: something no tool could answer, an answer that was wrong or confusing, or an error that did not say what would work. Its description tells the assistant to show you the note and send it only once you agree.

What is kept: the note, its kind, the tool it names, the client's name and version, the protocol and server versions, and the time. Never your IP address: only a keyed hash of it, to limit each address to 10 notes a day. A note holding an email address, an IP address or a web address with a query string is refused. Notes are read only by the people who run OpenPostcodes, and deleted after 365 days.

Protocol

• One endpoint, https://openpostcodes.uk/mcp, speaking Streamable HTTP over POST.
• Modern clients use protocol version 2026-07-28: no handshake, per-request _meta, server/discover, and the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers.
• Legacy clients use initialize with 2025-11-25, 2025-06-18 or 2025-03-26. A legacy request without the MCP-Protocol-Version header is treated as 2025-03-26, the only revision that allows batches (up to 10 messages). Older revisions never see fields added after them.
• Stateless: no sessions, no Mcp-Session-Id, no cookies and no GET stream. A GET from an MCP client gets 405; a browser gets this page.
• Every answer is a single JSON response but one: a modern client's subscriptions/listen gets a short event stream that acknowledges it and ends at once, since nothing is ever pushed.
• Tools, resources, prompts and completions. No logging, resource subscriptions, change notifications, sampling, elicitation or tasks.
• No OAuth and no API keys: the server never asks a client to sign in. Requests from every origin are allowed (CORS).
• Discovery documents: the server card and the AI catalog. The site's source also holds a server.json for the official MCP Registry.

OpenPostcodes is an open, read-only lookup of every live UK postcode, with the Channel Islands and the Isle of Man, from the ONS Postcode Directory (Open Government Licence v3.0). A postcode is identified by itself, in any spelling ("EX11 1RE", "ex111re"); above it are its sector ("EX11 1"), district ("EX11") and area ("EX").

For each it holds the centroid and grid references, the geographies it is in (local authority, ward, constituency, census and NHS areas), deprivation, the nearest station, GP, school and other services, utility companies, broadband, bordering postcodes and a boundary.

Coverage: terminated postcodes are not held. Coordinates are centroids. Deprivation ranks do not compare across countries. Nearest places, boundaries and utilities vary by country and are approximate. No addresses, and no search from a point to its postcode.

Lists are capped and paged; pass next_cursor back as cursor for more.

Start with get_postcode, lookup_postcodes for up to 100 at once, or compare_postcodes; browse with get_postcode_sector, get_postcode_district and get_postcode_area. The guide (https://openpostcodes.uk/mcp/guide.md) explains the fields and the limits.

Cite the openpostcodes.uk links in results, and give the attribution each result carries (ONS, Ordnance Survey and Royal Mail, and OpenStreetMap for nearest places).

If no tool can answer what the user asked, or an answer looks wrong, offer to tell OpenPostcodes with send_feedback, and send it only once the user agrees.

Licence and attribution

The postcodes, their coordinates and their geographies come from the ONS Postcode Directory and are reused under the Open Government Licence v3.0. When you publish something built from it, include this attribution: Contains OS data © Crown copyright and database right 2026. Contains Royal Mail data © Royal Mail copyright and database right 2026. Source: Office for National Statistics licensed under the Open Government Licence v3.0. Nearest pharmacies, post offices and libraries are © OpenStreetMap contributors (ODbL), and every other source and its licence is on the sources page. Tool results carry the attribution that applies in every answer.

OpenPostcodes is an independent project and is not affiliated with the Office for National Statistics, Ordnance Survey or Royal Mail. The ONS Postcode Directory is the authoritative source: where anything here differs from it, the ONS's own release takes precedence.

OpenCommons

OpenPostcodes is one of the OpenCommons sites. Their MCP servers keep one contract (identity, paging, results, errors and feedback), so an assistant connected to more than one finds the same conventions in each. Where a record has a counterpart on another of the sites, its result links to it under external_links.

• OpenCharities, UK charities from the three regulators' registers: England and Wales, Scotland and Northern Ireland: https://opencharities.uk/mcp
• OpenCompanies, UK companies, officers, owners and accounts from Companies House: https://opencompanies.uk/mcp
• OpenProperties, residential property sales in England and Wales from HM Land Registry's Price Paid Data: https://openproperties.uk/mcp