ViaCEP Brasil MCP Server

O ViaCEP Brasil MCP Server conecta ferramentas de IA à API gratuita ViaCEP, permitindo consultar CEPs e endereços de todo o Brasil via linguagem natural.

Com ele, agentes de IA, assistentes e chatbots podem:

Recuperar o endereço completo a partir de um CEP
Descobrir o CEP de um endereço a partir de estado, cidade e logradouro
Validar e enriquecer dados de endereço brasileiro com informações do IBGE, DDD, SIAFI e GIA

---

Ferramentas disponíveis (Tools)

🔍 `buscar_endereco_por_cep`

Consulta informações completas de um endereço brasileiro a partir do CEP.

| Parâmetro | Tipo | Obrigatório | Descrição | | --------- | ------ | ----------- | ------------------------------------------------------------------- | | cep | string | ✅ Sim | CEP com 8 dígitos, com ou sem hífen (ex: 01001-000 ou 01001000) |

Retorna: CEP formatado, logradouro, complemento, unidade, bairro, localidade, UF, estado, região, DDD, código IBGE, GIA e SIAFI.

Exemplo de resposta:

✅ Endereço encontrado para o CEP 01001000:

📮 CEP: 01001-000
📍 Logradouro: Praça da Sé, lado ímpar
🏘️  Bairro: Sé
🏙️  Cidade: São Paulo - SP
🗺️  Estado: São Paulo
🌎 Região: Sudeste
📞 DDD: 11
🏛️  Código IBGE: 3550308
💼 GIA: 1004
🔖 SIAFI: 7107

---

🗺️ `buscar_cep_por_endereco`

Pesquisa CEPs brasileiros a partir de informações de endereço. Retorna até 50 resultados, ordenados por proximidade do nome do logradouro.

| Parâmetro | Tipo | Obrigatório | Descrição | | ------------ | ------ | ----------- | --------------------------------------------------------- | | uf | string | ✅ Sim | Sigla do estado com 2 letras (ex: SP, RJ, RS, MG) | | cidade | string | ✅ Sim | Nome da cidade — mínimo de 3 caracteres | | logradouro | string | ✅ Sim | Nome do logradouro/rua — mínimo de 3 caracteres |

Retorna: lista de CEPs com logradouro, bairro e cidade correspondentes.

Exemplo de resposta:

Busca por: Paulista, São Paulo/SP

✅ 4 endereço(s) encontrado(s):
──────────────────────────────────────────────────
[1] CEP: 01311-300
    Logradouro: Avenida Paulista (de 1 a 610 - lado par)
    Bairro: Bela Vista
    Cidade: São Paulo - SP
...

---

Instalação

Pré-requisitos

Node.js 18 ou superior
npm 9 ou superior
(Opcional) Docker para execução containerizada

Opção 1: Build a partir do código-fonte

# Clone ou baixe o repositório
git clone <url-do-repositorio>
cd viacep-brasil-mcpserver

# Instale as dependências
npm install

# Compile o TypeScript
npm run build

O servidor compilado estará em build/index.js.

Opção 2: Docker

Build da imagem

docker build -t viacep-brasil-mcpserver .

Execução com Docker

O servidor usa transporte stdio, portanto a flag -i é obrigatória:

docker run -i --rm viacep-brasil-mcpserver

---

Configuração nos Clientes MCP

VS Code (GitHub Copilot)

Adicione ao arquivo .vscode/mcp.json no seu workspace:

{
  "servers": {
    "viacep-brasil": {
      "type": "stdio",
      "command": "node",
      "args": ["/caminho/absoluto/para/viacep-brasil-mcpserver/build/index.js"]
    }
  }
}

Ou com Docker:

{
  "servers": {
    "viacep-brasil": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "viacep-brasil-mcpserver"]
    }
  }
}

Claude Desktop

Edite o arquivo de configuração:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "viacep-brasil": {
      "command": "node",
      "args": ["/caminho/absoluto/para/viacep-brasil-mcpserver/build/index.js"]
    }
  }
}

Com Docker:

{
  "mcpServers": {
    "viacep-brasil": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "viacep-brasil-mcpserver"]
    }
  }
}

Cursor

Adicione ao arquivo de configuração MCP do Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "viacep-brasil": {
      "command": "node",
      "args": ["/caminho/absoluto/para/viacep-brasil-mcpserver/build/index.js"]
    }
  }
}

Outros clientes MCP (genérico)

Qualquer cliente MCP com suporte a transporte stdio pode usar este servidor:

{
  "mcpServers": {
    "viacep-brasil": {
      "command": "node",
      "args": ["/caminho/para/build/index.js"]
    }
  }
}

---

Exemplos de Uso

Via MCP Inspector (UI)

# Inicia o Inspector com interface web em http://localhost:6274
npx @modelcontextprotocol/inspector node build/index.js

Configure no Inspector:

Transport: stdio
Command: node
Args: build/index.js

Via MCP Inspector (CLI)

# Listar todas as ferramentas disponíveis
mcp-inspector --cli node build/index.js --method tools/list

# Buscar endereço pelo CEP da Praça da Sé (SP)
mcp-inspector --cli node build/index.js \
  --method tools/call \
  --tool-name buscar_endereco_por_cep \
  --tool-arg 'cep="01001000"'

# Buscar endereço com hífen
mcp-inspector --cli node build/index.js \
  --method tools/call \
  --tool-name buscar_endereco_por_cep \
  --tool-arg 'cep="01001-000"'

# Buscar CEP por endereço — Avenida Paulista em São Paulo/SP
mcp-inspector --cli node build/index.js \
  --method tools/call \
  --tool-name buscar_cep_por_endereco \
  --tool-arg uf=SP \
  --tool-arg cidade="São Paulo" \
  --tool-arg logradouro=Paulista

# Buscar CEP por endereço — Porto Alegre/RS
mcp-inspector --cli node build/index.js \
  --method tools/call \
  --tool-name buscar_cep_por_endereco \
  --tool-arg uf=RS \
  --tool-arg cidade="Porto Alegre" \
  --tool-arg logradouro=Domingos

# Listar recursos disponíveis (resources)
mcp-inspector --cli node build/index.js --method resources/list

# Ler a documentação do servidor como recurso MCP
mcp-inspector --cli node build/index.js \
  --method resources/read \
  --uri viacep://docs/readme

Docker + MCP Inspector

npx @modelcontextprotocol/inspector --cli docker run -i --rm viacep-brasil-mcpserver \
  --method tools/list

---

Recursos disponíveis (Resources)

📄 `viacep://docs/readme`

Documentação completa do servidor em formato Markdown. Disponível a qualquer cliente MCP para consulta.

URI:       viacep://docs/readme
MIME type: text/markdown

---

Desenvolvimento

Compilar em modo watch

npm run dev

Build para produção

npm run build

Build da imagem Docker

# Build padrão
docker build -t viacep-brasil-mcpserver .

# Build com tag de versão
docker build -t viacep-brasil-mcpserver:1.0.0 .

---

API ViaCEP

Este servidor consome a API pública e gratuita ViaCEP.

| Endpoint | Descrição | | --------------------------------------------------------------- | ------------------------------------------- | | GET https://viacep.com.br/ws/{cep}/json/ | Retorna endereço completo a partir do CEP | | GET https://viacep.com.br/ws/{UF}/{cidade}/{logradouro}/json/ | Retorna lista de CEPs por endereço (até 50) |

Tratamento de erros:

CEP com formato inválido → HTTP 400 Bad Request
CEP válido mas inexistente → { "erro": "true" }
Cidade ou logradouro com menos de 3 caracteres → HTTP 400 Bad Request

⚠️ Atenção: O uso massivo da API para validação de bases de dados pode resultar no bloqueio automático do acesso por tempo indeterminado, conforme informado pelo ViaCEP.

---

Tecnologias

| Tecnologia | Versão | Uso | | ---------------------------------------------------------------------------- | ------ | ------------------------------------ | | MCP TypeScript SDK | 1.x | Framework do servidor MCP | | Zod | 3.x | Validação de esquemas dos parâmetros | | TypeScript | 5.7+ | Linguagem de desenvolvimento | | Node.js | 22+ | Runtime (recomendado) / 18+ (mínimo) | | Docker | — | Containerização (opcional) |

---

Licença

Este projeto está licenciado sob a MIT License.

ViaCEP Brasil MCP Server