# PostcodeDog MCP Server

**在你的 AI 工具里查邮编、校验地址**

把 Claude、ChatGPT、Codex、Cursor、VS Code 等 AI 工具接到 PostcodeDog。在熟悉的助手裡查 82 国邮编、按各国格式校验、解析整条地址。

Endpoint: https://postcode.dog/mcp

Streamable HTTP · 免注册 · 无需 API Key

> Source: https://postcode.dog/mcp/install

## 能做什么

用自然语言提问，助手会自动选对工具。

### 查码与校验

在 82 个国家里查邮编、城市或地名，并在填进地址前按该国格式校验一遍。

- 90210 是哪里？还有哪些国家用同一个号码？
- 75008 是合法的法国邮编吗？
- 东京涩谷的邮编是多少？
- 查一下德国慕尼黑，给我三个邮编。

### 覆盖范围

看清哪些国家有数据、各自是什么格式，以及每个国家的编码精度。

- 欧洲哪些国家你有数据？分别是什么格式？
- 英国和加拿大的邮编格式分别长什么样？
- 数据库里一共收录了多少个邮编？
- 列出你在亚洲覆盖的国家，每个给一个示例邮编。

### 地址解析

把整条地址拆成国家、行政区、城市和邮编，并在填表或打单前确认这个邮编真实存在。

- 解析：1 Infinite Loop, Cupertino, CA 95014, USA。
- 伦敦唐宁街 10 号的邮编是多少？
- 逐个检查这几个德国邮编：10115、80331、99999。
- 校验 SW1A 1AA，并告诉我它覆盖伦敦哪个区域。

## 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.

## 安装

选一个 AI 工具。不用登录、不用 API Key——填服务器 URL 就行。

### Claude Code

```bash
claude mcp add --transport http --scope user postcodedog https://postcode.dog/mcp
```

1. 在终端执行这条命令。
2. 启动 Claude Code，运行 /mcp，选择 postcodedog。

**验证一下：** 问一句「90210 是哪里？」

### Codex

```bash
codex mcp add postcodedog --url https://postcode.dog/mcp
```

`~/.codex/config.toml`

```toml
[mcp_servers.postcodedog]
url = "https://postcode.dog/mcp"
```

1. 用命令添加，或把配置块写进 ~/.codex/config.toml。
2. 启动 Codex。没有登录步骤——这个服务是公开的。

**验证一下：** 问一句「比弗利山庄 90210 是哪个邮编？」

### Gemini CLI

```bash
gemini mcp add --transport http --scope user postcodedog https://postcode.dog/mcp
```

`settings.json`

```json
{
  "mcpServers": {
    "postcodedog": {
      "httpUrl": "https://postcode.dog/mcp"
    }
  }
}
```

1. 用命令添加，或把配置块写进 Gemini CLI 设置。
2. 启动 Gemini CLI，运行 /mcp 确认 postcodedog 已连接。

**验证一下：** 问一句「75008 是合法的法国邮编吗？」

### VS Code

```bash
code --add-mcp '{"name":"postcodedog","type":"http","url":"https://postcode.dog/mcp"}'
```

`.vscode/mcp.json`

```json
{
  "servers": {
    "postcodedog": {
      "type": "http",
      "url": "https://postcode.dog/mcp"
    }
  }
}
```

1. 执行命令，或把配置块存成工作区的 .vscode/mcp.json。
2. 打开 MCP 视图，启动 postcodedog，然后问一个邮编问题。

**验证一下：** 问一句「德国和日本的邮编格式分别是什么？」

### Cursor

`~/.cursor/mcp.json`

```json
{
  "mcpServers": {
    "postcodedog": {
      "url": "https://postcode.dog/mcp"
    }
  }
}
```

1. 把配置块合并进 ~/.cursor/mcp.json，或项目里的 .cursor/mcp.json。
2. 打开 Cursor 设置 → MCP，启用 postcodedog，然后重载窗口。

**验证一下：** 问一句「你覆盖欧洲哪些国家？」

### Claude

```text
https://postcode.dog/mcp
```

1. 打开 Customize → Connectors，选择 Add → Custom → Web。
2. 名称填 PostcodeDog，粘贴服务器 URL，认证留空。
3. 点 Connect——工具立即可用，不需要登录。

**验证一下：** 问一句「解析 1 Infinite Loop, Cupertino, CA 95014, USA。」

### ChatGPT

```text
https://postcode.dog/mcp
```

1. 打开 Plugins，点 +，选择 Add custom MCP server。
2. 名称填 PostcodeDog，粘贴服务器 URL，认证方式选「No authentication」。
3. 创建插件，在新会话里问一个邮编问题。

**验证一下：** 问一句「东京涩谷的邮编是多少？」

### Amp

```bash
amp mcp add postcodedog https://postcode.dog/mcp
```

1. 执行命令。
2. Amp 首次连接即可用，没有登录步骤。

**验证一下：** 问一句「99999 在德国存在吗？」

### opencode

```bash
opencode mcp add postcodedog --global --url https://postcode.dog/mcp
```

1. 添加服务器。
2. 启动 opencode，直接问邮编问题；没有认证步骤。

**验证一下：** 问一句「美国有多少个叫 Springfield 的地方？」

### Other AI tools

任何支持 Streamable HTTP 远程 MCP 的 AI 工具都能用这个 URL 接进来。没有 OAuth 流程，也不需要注册客户端。

`mcp.json`

```json
{
  "mcpServers": {
    "postcodedog": {
      "type": "http",
      "url": "https://postcode.dog/mcp"
    }
  }
}
```

1. 把客户端指向服务器 URL，认证留空。
2. 服务是无状态的——不需要 session 头、不写 cookie、不需要 initialize 握手。

**验证一下：** 问一句「90210 是哪里？」

## 常见问题

### PostcodeDog MCP 服务是什么？

它通过 Model Context Protocol 把 Claude、ChatGPT、Cursor、Codex 等 AI 工具接到 PostcodeDog 的邮编数据库。助手可以查码、搜地名、按各国格式校验、解析地址，并说明覆盖范围。

### 需要 API Key 吗？

不需要。这个服务只读且公开：没有账号、没有 OAuth、没有 token 要复制。粘贴 URL 就是全部配置。

### 支持哪些 AI 工具？

任何支持 Streamable HTTP 远程 MCP 的工具。安装指南覆盖 Claude Code、Codex、Gemini CLI、VS Code、Cursor、Claude、ChatGPT、Amp 和 opencode。

### 助手能看到什么数据？

只有公开的邮编数据：82 个国家的约 180 万行 GeoNames 记录，包含地名、行政区、县、坐标和各国格式。没有账号，也就没有可泄露的个人数据。

### 它会修改什么吗？

不会。五个工具全是只读的：不能写入、提交或修改数据，不写 cookie，也不保留会话。

### 数据准吗？

数据来自 GeoNames 邮编库（CC BY 4.0），每次重建都会更新，地名和坐标都对应真实记录。各国编码精度不同，助手可以用 list_countries 查到具体国家的格式与可用范围。

### 有调用频率限制吗？

没有 Key，也没有硬性配额，但 PostcodeDog 是个小站：批量任务请控制频率。高并发或商业用途，请先联系我们。

### 怎么断开？

在 AI 工具的设置里移除这个服务器即可。我们这边不存任何东西，也没有其他需要撤销的授权。

---

Postal code data © GeoNames contributors, CC BY 4.0.
