# PostcodeDog MCP Server

**AI 도구에서 우편번호를 조회하고 검증하세요**

Claude, ChatGPT, Codex, Cursor, VS Code 같은 AI 도구를 PostcodeDog에 연결합니다. 익숙한 어시스턴트에서 82개국 우편번호를 조회하고, 국가별 형식으로 검증하고, 주소를 분해할 수 있습니다.

Endpoint: https://postcode.dog/mcp

Streamable HTTP · 가입 불필요 · API 키 불필요

> 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 키도 필요 없습니다——서버 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. 서버는 상태가 없습니다——세션 헤더, 쿠키, initialize 핸드셰이크가 필요 없습니다.

**확인해 보기:** “90210은 어디인가요?”라고 물어보기

## 자주 묻는 질문

### PostcodeDog MCP 서버란 무엇인가요?

Model Context Protocol을 통해 Claude, ChatGPT, Cursor, Codex 같은 AI 도구를 PostcodeDog의 우편번호 데이터베이스에 연결합니다. 우편번호 조회, 지명 검색, 국가 형식 검증, 주소 분석, 커버리지 확인을 할 수 있습니다.

### API 키가 필요한가요?

아니요. 읽기 전용 공개 서버입니다. 계정도 OAuth도 토큰도 없습니다. URL을 붙여 넣는 것이 전부입니다.

### 어떤 AI 도구에서 되나요?

Streamable HTTP 원격 MCP를 지원하는 도구면 모두 됩니다. 가이드에서는 Claude Code, Codex, Gemini CLI, VS Code, Cursor, Claude, ChatGPT, Amp, opencode를 다룹니다.

### 어시스턴트가 무엇을 볼 수 있나요?

공개 우편번호 데이터만 봅니다. 82개국 약 180만 행의 GeoNames 레코드(지명, 지역, 카운티, 좌표, 국가 형식)입니다. 계정이 없으니 노출될 개인정보도 없습니다.

### 무언가를 바꾸나요?

아니요. 다섯 도구 모두 읽기 전용입니다. 쓰기, 제출, 수정이 불가능하고 쿠키도 세션도 남기지 않습니다.

### 데이터는 정확한가요?

GeoNames 우편번호 데이터(CC BY 4.0)이며 다시 빌드할 때마다 갱신됩니다. 지명과 좌표는 실제 기록을 따릅니다. 국가마다 정밀도가 다르므로 list_countries로 각국의 형식과 사용 가능한 범위를 확인할 수 있습니다.

### 호출 제한이 있나요?

키도 엄격한 할당량도 없지만 PostcodeDog은 작은 사이트입니다. 대량 작업은 상식적인 속도로 유지해 주세요. 고부하나 상업적 사용은 먼저 문의해 주세요.

### 연결을 끊으려면?

AI 도구 설정에서 서버를 제거하면 됩니다. 저희 쪽에는 아무것도 저장하지 않으므로 취소할 것이 없습니다.

---

Postal code data © GeoNames contributors, CC BY 4.0.