Postcodes

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:

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

For local stdio use, configure the package command:

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