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.