# postcodes [Health: Active]

**Category:** 🗺️ Location Services  
**Repository:** https://github.com/pipeworx-io/mcp-postcodes  
**GitHub Stars:** 0  
**npm Downloads (last month):** 430  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/postcodes

## Description
Postcodes MCP — wraps postcodes.io UK postcode API (free, no auth)

## Tools
Capabilities this server exposes over MCP:

- **lookup_postcode** — Get geographic details for a UK postcode (e.g., 'SW1A 1AA'). Returns coordinates, region, district, ward, and constituency.
- **nearest_postcodes** — Find nearby UK postcodes sorted by distance from a given postcode (e.g., 'SW1A 1AA'). Returns list with coordinates.
- **validate_postcode** — Validate a UK postcode format (e.g., 'SW1A 1AA'). Returns whether it's valid and format details.
- **random_postcode** — Get a random valid UK postcode with full geographic details. Returns coordinates, region, district, ward, and constituency.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "postcodes": {
    "command": "npx",
    "args": ["-y","@pipeworx/mcp-postcodes"]
  }
}
```

## Documentation

## What the postcodes MCP server does

The postcodes MCP server exposes four MCP tools for working with UK postcodes through the postcodes.io API. It is suited to agents that need to check a postcode, retrieve geographic attributes, identify nearby postcodes, or produce a valid postcode for testing and example data.

`lookup_postcode` returns geographic information for a supplied postcode, including coordinates, region, district, ward, and constituency. `validate_postcode` checks whether a postcode follows a valid UK format and returns format-related details. `nearest_postcodes` finds nearby postcodes and orders the results by distance from the supplied postcode, with coordinates included. `random_postcode` returns a randomly selected valid UK postcode with geographic details.

## How it works

The postcodes MCP server can be reached through the Pipeworx gateway or run as a standalone local process. The gateway exposes a scoped MCP endpoint at `https://gateway.pipeworx.io/postcodes/mcp`. That endpoint lists the postcode tools along with shared Pipeworx meta-tools. The gateway can also be connected at `https://gateway.pipeworx.io/mcp`, where the broader catalog is listed directly.

A local installation communicates through standard input and output. Running `npx -y @pipeworx/mcp-postcodes` starts the package without a gateway account or gateway round trip. In standalone mode, the MCP connection exposes only the four postcode tools rather than the shared gateway tools.

The gateway also provides direct HTTP access. For example, a client can send a JSON POST request to `https://gateway.pipeworx.io/v1/tools/postcodes_lookup_postcode` with a `postcode` value. Gateway users can alternatively call `ask_pipeworx` with a natural-language question; the gateway selects and invokes an appropriate tool.

## Setup and configuration

For an MCP client that supports remote HTTP servers, add the scoped gateway URL:

```json
{
  "mcpServers": {
    "postcodes": {
      "url": "https://gateway.pipeworx.io/postcodes/mcp"
    }
  }
}
```

For local stdio use, configure the package command:

```json
{
  "mcpServers": {
    "postcodes": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-postcodes"]
    }
  }
}
```

No authentication is required for the postcodes.io service, and the README states that initial gateway calls do not require an account. The package does not document any required environment variables.

## Tools and capabilities

- `lookup_postcode`: retrieves coordinates and administrative details for a UK postcode.
- `nearest_postcodes`: returns nearby postcodes sorted by distance, including coordinates.
- `validate_postcode`: checks UK postcode formatting and reports whether the input is valid.
- `random_postcode`: generates a valid UK postcode with geographic details.

The tools are designed around UK postcode data; the supplied examples use values such as `SW1A 1AA`. They do not document address search, reverse geocoding, international postal codes, or postcode mutation operations.

## Limitations and notes

Gateway pack endpoints include shared Pipeworx meta-tools in addition to the postcode tools, so `tools/list` may report more tools than the four documented here. The exact gateway scope is stated in the MCP `initialize` response and may change. Use the local package when a connection limited to the postcode tools is preferred.

The README identifies postcodes.io as free and requiring no authentication. It does not specify rate limits, uptime guarantees, response schemas beyond the listed fields, or behavior for malformed and nonexistent postcodes. The project is licensed under MIT.

_Full upstream README: https://allmcps.com/mcp/postcodes/readme_