# PostcodeDog MCP Server

**Look Up and Validate Postal Codes from Your AI Tools**

Connect Claude, ChatGPT, Codex, Cursor, VS Code, and other AI tools to PostcodeDog. Resolve postal codes in 82 countries, validate them against national formats, and parse addresses from the assistants you already use.

Endpoint: https://postdog.zhangjunrock.workers.dev/mcp

Streamable HTTP · No sign-up · No API key

> Source: https://postdog.zhangjunrock.workers.dev/mcp/install

## What you can do

Ask in plain language. Your assistant picks the right tool.

### Look up and validate

Resolve a postal code, a city, or a place name across 82 countries, and check a code against the national format before it goes into an address.

- What is 90210, and which other countries use the same code?
- Is 75008 a valid French postal code?
- Which postcode does Shibuya, Tokyo use?
- Look up Munich in Germany and show me three codes.

### Explore coverage

See which countries are covered, what format each one uses, and how precise the data is per country.

- Which European countries do you cover, and what formats do they use?
- What do UK and Canadian postcodes look like?
- How many postal codes are in the database?
- List the countries you cover in Asia, with an example code for each.

### Work with addresses

Split a full address into country, region, city, and postal code, then confirm the code exists before you put it in a form or a shipment.

- Parse 1 Infinite Loop, Cupertino, CA 95014, USA.
- Which postal code belongs to 10 Downing Street, London?
- Check these German codes one by one: 10115, 80331, 99999.
- Validate SW1A 1AA and tell me which London area it covers.

## Tools

- `lookup_postal_code` — Resolve a postal code, city, or place name; optional country and limit.
- `search_places` — Full-text search over place names, optionally limited to one country.
- `validate_postal_code` — Check a code against the national format and the database.
- `parse_address` — Split a free-form or labelled address into fields and resolve its code.
- `list_countries` — List covered countries with format, example, coverage note, and counts.

## Install

Pick your AI tool. There is no sign-in and no API key — the server URL is all you need.

### Claude Code

```bash
claude mcp add --transport http --scope user postcodedog https://postdog.zhangjunrock.workers.dev/mcp
```

1. Run the command in your terminal.
2. Start Claude Code, run /mcp, and pick postcodedog.

**Check it works:** ask “What is 90210?”

### Codex

```bash
codex mcp add postcodedog --url https://postdog.zhangjunrock.workers.dev/mcp
```

`~/.codex/config.toml`

```toml
[mcp_servers.postcodedog]
url = "https://postdog.zhangjunrock.workers.dev/mcp"
```

1. Add the server with the command, or add the block to ~/.codex/config.toml.
2. Start Codex. There is no login step — the server is public.

**Check it works:** ask “Which postal code is Beverly Hills 90210?”

### Gemini CLI

```bash
gemini mcp add --transport http --scope user postcodedog https://postdog.zhangjunrock.workers.dev/mcp
```

`settings.json`

```json
{
  "mcpServers": {
    "postcodedog": {
      "httpUrl": "https://postdog.zhangjunrock.workers.dev/mcp"
    }
  }
}
```

1. Add the server with the command, or add the block to Gemini CLI settings.
2. Start Gemini CLI and run /mcp to confirm postcodedog is connected.

**Check it works:** ask “Is 75008 a valid French postal code?”

### VS Code

```bash
code --add-mcp '{"name":"postcodedog","type":"http","url":"https://postdog.zhangjunrock.workers.dev/mcp"}'
```

`.vscode/mcp.json`

```json
{
  "servers": {
    "postcodedog": {
      "type": "http",
      "url": "https://postdog.zhangjunrock.workers.dev/mcp"
    }
  }
}
```

1. Run the command, or save the block as .vscode/mcp.json in your workspace.
2. Open the MCP view, start postcodedog, and ask a postcode question.

**Check it works:** ask “List the postcode formats for Germany and Japan.”

### Cursor

`~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "postcodedog": {
      "url": "https://postdog.zhangjunrock.workers.dev/mcp"
    }
  }
}
```

1. Merge the block into ~/.cursor/mcp.json, or into .cursor/mcp.json in the project.
2. Open Cursor settings → MCP, enable postcodedog, and reload the window.

**Check it works:** ask “Which countries in Europe do you cover?”

### Claude

```text
https://postdog.zhangjunrock.workers.dev/mcp
```

1. Open Customize → Connectors, then Add → Custom → Web.
2. Name it PostcodeDog, paste the server URL, and leave authentication empty.
3. Select Connect — the tools are available immediately, with no sign-in.

**Check it works:** ask “Parse 1 Infinite Loop, Cupertino, CA 95014, USA.”

### ChatGPT

```text
https://postdog.zhangjunrock.workers.dev/mcp
```

1. Open Plugins, select +, then Add custom MCP server.
2. Name it PostcodeDog, paste the server URL, and choose “No authentication”.
3. Create the plugin and ask a postcode question in a new chat.

**Check it works:** ask “Find the postcode for Shibuya, Tokyo.”

### Amp

```bash
amp mcp add postcodedog https://postdog.zhangjunrock.workers.dev/mcp
```

1. Run the command.
2. Amp connects on first use; there is no sign-in step.

**Check it works:** ask “Check whether 99999 exists in Germany.”

### opencode

```bash
opencode mcp add postcodedog --global --url https://postdog.zhangjunrock.workers.dev/mcp
```

1. Add the server.
2. Start opencode and ask a postcode question; there is no auth step.

**Check it works:** ask “How many places are called Springfield in the US?”

### Other AI tools

Any AI tool that supports remote MCP servers over Streamable HTTP can connect with the server URL. There is no OAuth flow to implement and no client registration.

`mcp.json`

```json
{
  "mcpServers": {
    "postcodedog": {
      "type": "http",
      "url": "https://postdog.zhangjunrock.workers.dev/mcp"
    }
  }
}
```

1. Point the client at the server URL; leave authentication unset.
2. The server is stateless — no session header, no cookies, no initialize handshake required.

**Check it works:** ask “What is 90210?”

## Questions

### What is the PostcodeDog MCP server?

It connects AI tools like Claude, ChatGPT, Cursor, and Codex to PostcodeDog’s postal code database through the Model Context Protocol. Your assistant can look up codes, search places, validate codes against national formats, parse addresses, and report coverage.

### Do I need an API key?

No. The server is read-only and public: there is no account, no OAuth, and no token to copy. Pasting the URL is the whole setup.

### Which AI tools does it work with?

Any tool that supports remote MCP servers over Streamable HTTP. The install guide covers Claude Code, Codex, Gemini CLI, VS Code, Cursor, Claude, ChatGPT, Amp, and opencode.

### What can my assistant see?

Only public postal data: 1.8 million GeoNames rows across 82 countries, with place names, regions, counties, coordinates, and national formats. There is nothing personal to expose because there are no accounts.

### Can it change anything?

No. All five tools are read-only. The server cannot write, submit, or modify data, it sets no cookies, and it keeps no session.

### How accurate is the data?

It is the GeoNames postal database, licensed CC BY 4.0, refreshed with each rebuild. Place names and coordinates come from real records. Precision differs by country; list_countries reports the format and available coverage for each one.

### Is there a rate limit?

There is no key and no hard quota, but PostcodeDog is a small site: keep bulk jobs to a reasonable rate. For high-volume or commercial use, contact us before you point a crawler at it.

### How do I disconnect?

Remove the server from your AI tool’s settings. Nothing is stored on our side, so there is nothing else to revoke.

---

Postal code data © GeoNames contributors, CC BY 4.0.