# PostcodeDog MCP Server

**Consulte e valide códigos postais nas suas ferramentas de IA**

Ligue Claude, ChatGPT, Codex, Cursor, VS Code e outras ferramentas de IA ao PostcodeDog. Consulte códigos postais em 82 países, valide-os segundo o formato nacional e decomponha endereços a partir do seu assistente.

Endpoint: https://postcode.dog/mcp

Streamable HTTP · Sem registo · Sem chave API

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

## O que pode fazer

Pergunte em linguagem natural. O assistente escolhe a ferramenta certa.

### Consultar e validar

Encontre um código postal, uma cidade ou um lugar em 82 países e verifique o código segundo o formato nacional antes de o usar num endereço.

- O que é 90210 e que outros países usam o mesmo código?
- 75008 é um código postal francês válido?
- Qual é o código postal de Shibuya, Tóquio?
- Consulte Munique na Alemanha e mostre-me três códigos.

### Ver a cobertura

Veja que países estão cobertos, que formato usam e qual é a precisão dos dados em cada país.

- Que países europeus cobre e que formatos usam?
- Como são os códigos postais do Reino Unido e do Canadá?
- Quantos códigos postais existem na base?
- Liste os países cobertos na Ásia, com um código de exemplo para cada.

### Trabalhar com endereços

Divida um endereço completo em país, região, cidade e código postal e confirme que o código existe antes de o pôr num formulário ou numa etiqueta.

- Decomponha 1 Infinite Loop, Cupertino, CA 95014, USA.
- Que código postal corresponde a 10 Downing Street, Londres?
- Verifique estes códigos alemães um a um: 10115, 80331, 99999.
- Valide SW1A 1AA e diga-me que zona de Londres cobre.

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

## Instalação

Escolha a sua ferramenta de IA. Sem registo e sem chave API — o URL do servidor é tudo o que precisa.

### Claude Code

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

1. Execute o comando no terminal.
2. Abra o Claude Code, execute /mcp e escolha postcodedog.

**Para testar:** pergunte «O que é 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. Adicione o servidor com o comando ou o bloco em ~/.codex/config.toml.
2. Abra o Codex. Não há passo de login — o servidor é público.

**Para testar:** pergunte «Que código postal é Beverly Hills 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. Adicione o servidor com o comando ou o bloco nas definições do Gemini CLI.
2. Abra o Gemini CLI e execute /mcp para confirmar que o postcodedog está ligado.

**Para testar:** pergunte «75008 é um código postal francês válido?»

### 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. Execute o comando ou guarde o bloco como .vscode/mcp.json no workspace.
2. Abra a vista MCP, inicie o postcodedog e faça uma pergunta de código postal.

**Para testar:** pergunte «Quais são os formatos dos códigos postais da Alemanha e do Japão?»

### Cursor

`~/.cursor/mcp.json`

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

1. Junte o bloco em ~/.cursor/mcp.json ou em .cursor/mcp.json do projeto.
2. Abra as definições do Cursor → MCP, ative o postcodedog e recarregue a janela.

**Para testar:** pergunte «Que países da Europa cobre?»

### Claude

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

1. Abra Customize → Connectors e escolha Add → Custom → Web.
2. Dê o nome PostcodeDog, cole o URL do servidor e deixe a autenticação vazia.
3. Selecione Connect — as ferramentas ficam disponíveis de imediato, sem login.

**Para testar:** pergunte «Decomponha 1 Infinite Loop, Cupertino, CA 95014, USA.»

### ChatGPT

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

1. Abra Plugins, escolha + e depois Add custom MCP server.
2. Dê o nome PostcodeDog, cole o URL e escolha «No authentication».
3. Crie o plugin e faça uma pergunta de código postal num chat novo.

**Para testar:** pergunte «Qual é o código postal de Shibuya, Tóquio?»

### Amp

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

1. Execute o comando.
2. O Amp liga-se no primeiro uso; não há login.

**Para testar:** pergunte «99999 existe na Alemanha?»

### opencode

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

1. Adicione o servidor.
2. Abra o opencode e faça uma pergunta de código postal; sem autenticação.

**Para testar:** pergunte «Quantos lugares se chamam Springfield nos EUA?»

### Other AI tools

Qualquer ferramenta de IA que suporte servidores MCP remotos por Streamable HTTP pode ligar-se com o URL. Não há fluxo OAuth nem registo de cliente.

`mcp.json`

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

1. Aponte o cliente para o URL do servidor e deixe a autenticação vazia.
2. O servidor não tem estado — sem cabeçalho de sessão, sem cookies, sem handshake initialize.

**Para testar:** pergunte «O que é 90210?»

## Perguntas

### O que é o servidor MCP do PostcodeDog?

Liga ferramentas de IA como Claude, ChatGPT, Cursor e Codex à base de códigos postais do PostcodeDog através do Model Context Protocol. O assistente pode consultar códigos, pesquisar lugares, validar formatos nacionais, decompor endereços e indicar a cobertura.

### Preciso de uma chave API?

Não. O servidor é público e só de leitura: sem conta, sem OAuth e sem token. Colar o URL é toda a configuração.

### Com que ferramentas de IA funciona?

Com qualquer ferramenta que suporte servidores MCP remotos por Streamable HTTP. O guia cobre Claude Code, Codex, Gemini CLI, VS Code, Cursor, Claude, ChatGPT, Amp e opencode.

### O que pode o meu assistente ver?

Apenas dados postais públicos: cerca de 1,8 milhões de linhas do GeoNames em 82 países, com nomes de lugares, regiões, condados, coordenadas e formatos nacionais. Não há contas, logo não há dados pessoais.

### Pode alterar alguma coisa?

Não. As cinco ferramentas são só de leitura. O servidor não escreve, submete ou modifica dados, não define cookies e não guarda sessão.

### Os dados são exatos?

É a base postal do GeoNames, licenciada CC BY 4.0, atualizada a cada reconstrução. Nomes e coordenadas vêm de registos reais. A precisão varia por país; o list_countries indica o formato e a cobertura disponível para cada um.

### Há limite de pedidos?

Não há chave nem quota rígida, mas o PostcodeDog é um site pequeno: mantenha os lotes a um ritmo razoável. Para uso intensivo ou comercial, fale connosco primeiro.

### Como desligo?

Remova o servidor das definições da ferramenta de IA. Não guardamos nada do nosso lado, por isso não há mais nada a revogar.

---

Postal code data © GeoNames contributors, CC BY 4.0.