ViaCEP Brasil MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ViaCEP Brasil MCP Server look up address for CEP 01001000"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| string | ✅ Sim | CEP com 8 dígitos, com ou sem hífen (ex: |
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 |
| string | ✅ Sim | Sigla do estado com 2 letras (ex: |
| string | ✅ Sim | Nome da cidade — mínimo de 3 caracteres |
| 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
...Related MCP server: ViaCEP Brasil MCP Server
Instalação
Pré-requisitos
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 buildO 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-mcpserverConfiguraçã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.jsonWindows:
%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.jsConfigure no Inspector:
Transport:
stdioCommand:
nodeArgs:
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/readmeDocker + MCP Inspector
npx @modelcontextprotocol/inspector --cli docker run -i --rm viacep-brasil-mcpserver \
--method tools/listRecursos 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/markdownDesenvolvimento
Compilar em modo watch
npm run devBuild para produção
npm run buildBuild 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 |
| Retorna endereço completo a partir do CEP |
| Retorna lista de CEPs por endereço (até 50) |
Tratamento de erros:
CEP com formato inválido → HTTP
400 Bad RequestCEP 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 |
1.x | Framework do servidor MCP | |
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.
Available Tools
2 toolsbuscar_cep_por_enderecoA
Pesquisa CEPs brasileiros a partir de informações de endereço: UF (sigla do estado), cidade e logradouro (nome da rua/avenida/etc). Retorna até 50 CEPs correspondentes, ordenados pela proximidade do nome do logradouro. Útil quando o CEP não é conhecido mas o endereço sim.
Inputs: uf (required), cidade (required), logradouro (required).
buscar_endereco_por_cepA
Consulta informações completas de um endereço brasileiro a partir do CEP (Código de Endereçamento Postal). Retorna logradouro, bairro, cidade, estado, região, DDD, IBGE, GIA e SIAFI. O CEP pode ser informado com ou sem hífen (ex: 01001-000 ou 01001000).
Inputs: cep (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools are inverse operations: one fetches an address from a CEP, the other fetches CEPs from an address. Their purposes are clearly distinct and complementary, leaving no ambiguity.
Both tool names follow the same Portuguese pattern 'buscar_X_por_Y' (buscar_endereco_por_cep and buscar_cep_por_endereco), making the naming perfectly consistent and predictable.
With only 2 tools, the count is borderline but appropriate for the narrow domain of CEP lookup. Each tool covers one direction of the search, so no tool feels superfluous.
The server covers the two core operations of the ViaCEP service: address-by-CEP and CEP-by-address. This fully addresses the domain's primary use cases, with no obvious gaps.
Maintenance
Related MCP Connectors
Returns the postal code (CEP) and standardized address from the Brazilian Post from a given address.
Brazil's Correios for AI agents: shipping quotes (frete), tracking (rastreio) and labels (etiqueta).
Correios: CEP, official-source lookup. Platform-hosted, pay per query with prepaid credit.
Correios: Completa CEP (CEP + Área territorial brasileira), official-source lookup. Platform-hosted,
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables lookup of Brazilian addresses by CEP (postal code) using the ViaCEP API, returning formatted address information including street, neighborhood, city, and state.1ISC
- FlicenseAqualityDmaintenanceEnables AI tools to query Brazilian addresses by CEP or search CEPs by address via the ViaCEP API.2-
- AlicenseNot gradedqualityDmaintenanceEnables querying Brazilian CEP (postal code) addresses via the public ViaCEP API, returning formatted HTML with address details.GPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables Brazilian address lookup by CEP and reverse lookup from UF, city, and street via the public ViaCEP API.MIT