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