# Postio MCP server

> Validates UK addresses, postcodes, emails, and phone numbers using Royal Mail PAF, live SMTP, and HLR data.

- Repository: https://github.com/postio-uk/postio-integrations
- Page: https://hostedmcp.org/servers/postio-uk/postcode-address-validation
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 0.1.5

## Install

### Claude Code

```sh
claude mcp add --env 'POSTIO_API_KEY=<YOUR_POSTIO_API_KEY>' postcode-address-validation -- npx -y @postio/mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "postcode-address-validation": {
      "command": "npx",
      "args": [
        "-y",
        "@postio/mcp"
      ],
      "env": {
        "POSTIO_API_KEY": "<YOUR_POSTIO_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "postcode-address-validation": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@postio/mcp"
      ],
      "env": {
        "POSTIO_API_KEY": "<YOUR_POSTIO_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"postcode-address-validation","type":"stdio","command":"npx","args":["-y","@postio/mcp"],"env":{"POSTIO_API_KEY":"<YOUR_POSTIO_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "postcode-address-validation": {
      "command": "npx",
      "args": [
        "-y",
        "@postio/mcp"
      ],
      "env": {
        "POSTIO_API_KEY": "<YOUR_POSTIO_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add postcode-address-validation --env 'POSTIO_API_KEY=<YOUR_POSTIO_API_KEY>' -- npx -y @postio/mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.postcode-address-validation]
command = "npx"
args = ["-y", "@postio/mcp"]

[mcp_servers.postcode-address-validation.env]
POSTIO_API_KEY = "<YOUR_POSTIO_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'POSTIO_API_KEY=<YOUR_POSTIO_API_KEY>' postcode-address-validation npx -- -y @postio/mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "postcode-address-validation": {
      "command": "npx",
      "args": [
        "-y",
        "@postio/mcp"
      ],
      "env": {
        "POSTIO_API_KEY": "<YOUR_POSTIO_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `POSTIO_API_KEY` | yes | yes | Postio API key (pk_…). Free key, first 100 lookups on us, no card: https://postio.co.uk/signup |
| `POSTIO_BASE_URL` | no | no | Override the API base URL. Defaults to https://api.postio.co.uk/v1 (include /v1). Only needed for staging. |

## Tools (6)

- `postio_address_search`
- `postio_postcode_lookup`
- `postio_udprn_lookup`
- `postio_email_validate`
- `postio_phone_validate`
- `postio_connect`

## FAQ

### Can I use this with Claude Desktop?

Yes, you can configure it in your Claude Desktop configuration file using npx.

### What happens if I don't provide an API key?

The server will still start and list its tools, but individual tool calls will fail with a message instructing you to set the key.