Skip to main content
Glama
edum-compassuol

ViaCEP Brasil MCP Server

by edum-compassuol
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

ViaCEP Brasil MCP Server

O ViaCEP Brasil MCP Server conecta ferramentas de IA diretamente à API ViaCEP, permitindo consultas de endereços brasileiros através do CEP ou busca de CEPs através de endereços. Esta integração permite que agentes de IA, assistentes e chatbots consultem informações de endereços do Brasil por meio de interações em linguagem natural.

Casos de Uso

  • Consulta de Endereços: Obtenha informações detalhadas de endereços fornecendo um CEP.

  • Busca de CEPs: Encontre CEPs a partir de informações parciais de endereços (UF, cidade e logradouro).

  • Validação de Endereços: Verifique se um CEP existe e obtenha os detalhes completos do endereço.

  • Integração com Sistemas: Facilite a integração de dados de endereço em aplicações que utilizam IA.

Related MCP server: ViaCEP Brasil MCP Server

Ferramentas Disponíveis

O servidor disponibiliza duas ferramentas principais:

getAddressByCEP

Obtém informações de endereço a partir de um CEP.

Parâmetros:

  • cep (string): O código postal de 8 dígitos, sem hífen ou outros caracteres especiais.

Exemplo de Uso:

{
  "cep": "01001000"
}

Exemplo de Resposta:

{
  "cep": "01001-000",
  "logradouro": "Praça da Sé",
  "complemento": "lado ímpar",
  "bairro": "Sé",
  "localidade": "São Paulo",
  "uf": "SP",
  "ibge": "3550308",
  "gia": "1004",
  "ddd": "11",
  "siafi": "7107"
}

getCEPByAddress

Busca CEPs com base em informações de endereço.

Parâmetros:

  • uf (string): Código de duas letras do estado (ex: "SP").

  • cidade (string): Nome da cidade.

  • logradouro (string): Nome da rua, avenida, praça, etc.

Exemplo de Uso:

{
  "uf": "RS",
  "cidade": "Porto Alegre",
  "logradouro": "Domingos"
}

Exemplo de Resposta:

[
  {
    "cep": "91420-270",
    "logradouro": "Rua São Domingos",
    "bairro": "Bom Jesus",
    "localidade": "Porto Alegre",
    "uf": "RS",
    ...
  },
  {
    "cep": "91040-000",
    "logradouro": "Rua Domingos Rubbo",
    "bairro": "Cristo Redentor",
    "localidade": "Porto Alegre",
    "uf": "RS",
    ...
  },
  ...
]

Recursos

  • README: Acesse esta documentação através do recurso readme://viacep.

Instalação e Configuração

O ViaCEP Brasil MCP Server pode ser executado de várias formas, dependendo das suas necessidades.

Pré-requisitos

  • Node.js v18+ (para execução direta)

  • Docker (para execução via contêiner)

Instalação via NPX

A forma mais simples de usar o servidor:

npx viacep-brasil-mcp-server

Instalação Local

Clone este repositório e execute:

# Instalar dependências
npm install

# Construir o servidor
npm run build

# Iniciar o servidor
node build/index.js

Instalação via Docker

Usando a Imagem Pré-construída

docker run -i --rm ghcr.io/seu-usuario/viacep-brasil-mcp-server

Construindo sua Própria Imagem

# Clone o repositório
git clone https://github.com/seu-usuario/viacep-brasil-mcp-server.git
cd viacep-brasil-mcp-server

# Construa a imagem Docker
docker build -t viacep-brasil-mcp-server .

# Execute o contêiner
docker run -i --rm viacep-brasil-mcp-server

Configuração em Aplicações MCP

VS Code com GitHub Copilot

Adicione o seguinte bloco JSON às suas configurações MCP:

{
  "servers": {
    "viacep": {
      "command": "npx",
      "args": ["viacep-brasil-mcp-server"]
    }
  }
}

VS Code com Docker

{
  "servers": {
    "viacep": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "viacep-brasil-mcp-server"
      ]
    }
  }
}

Claude Desktop / Claude Web / Claude Code

Adicione o servidor ao arquivo de configuração:

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

{
  "mcpServers": {
    "viacep": {
      "command": "/caminho/para/viacep-brasil-mcp-server/build/index.js"
    }
  }
}

Cursor

Adicione o seguinte ao seu arquivo .cursor/mcp.json:

{
  "servers": {
    "viacep": {
      "command": "npx",
      "args": ["viacep-brasil-mcp-server"]
    }
  }
}

Desenvolvimento

Instalação de Dependências

npm install

Construir o Servidor

npm run build

Desenvolvimento com Auto-reconstrução

npm run watch

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Recomendamos usar o MCP Inspector, que está disponível como um script de pacote:

npm run inspector

O Inspector fornecerá um URL para acessar ferramentas de depuração em seu navegador.

Licença

Este projeto é licenciado sob os termos da licença MIT de código aberto.

Available Tools

2 tools
getAddressByCEPA

Fetches a Brazilian address using a postal code (CEP).

ParametersJSON Schema
NameRequiredDescriptionDefault
cepYesThe 8-digit CEP code.

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. 'Fetches' implies a read-only operation, but it does not disclose error handling, input validation, formatting expectations, or response structure. Lacks detail beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the verb and resource. No wasted words; it is appropriately sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with full schema coverage, the description plus schema are nearly complete. It lacks explicit return format details, but the purpose statement implies the output. Given the simplicity, it is adequately complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the 'cep' parameter described as 'The 8-digit CEP code.' The tool description mentions 'postal code (CEP)' but adds no additional meaning beyond the schema. Baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Fetches') and names the resource ('Brazilian address') and the input ('postal code (CEP)'). It clearly distinguishes from the sibling tool getCEPByAddress, which performs the reverse operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have a CEP and need an address, but it does not explicitly state when to use this tool over getCEPByAddress or mention any exclusions. No alternative tools are referenced.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getCEPByAddressA

Fetches a list of CEPs based on a Brazilian address.

ParametersJSON Schema
NameRequiredDescriptionDefault
ufYesThe two-letter state code (e.g., SP).
cidadeYesThe city name.
logradouroYesThe street name.

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only says 'fetches a list' but does not disclose behavior like result limits, error conditions, or whether multiple CEPs are expected. Minimal behavioral detail is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is clear and front-loaded. Every word serves a purpose, with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple three-parameter lookup tool with no output schema or annotations, the description provides minimal but adequate context. However, it lacks details about result format, potential errors, or differentiation from the sibling tool, leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (all three parameters have descriptions). The description adds no additional meaning beyond what the schema already provides, so it meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetches') and resource ('list of CEPs based on a Brazilian address'). It distinguishes from the sibling getAddressByCEP, which performs the reverse lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for converting an address to CEPs, but it does not explicitly state when to use it versus getAddressByCEP or any exclusions. Usage is inferred from the name and description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedgetAddressByCEP
    • First observedgetCEPByAddress
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools perform reverse operations—one returns an address for a given CEP, the other returns CEPs for a given address. Their purposes are clearly distinct with no overlap.

Naming Consistency5/5

Both tools follow a consistent 'get<Target>By<Query>' pattern, e.g., 'getAddressByCEP' and 'getCEPByAddress'. The naming is symmetric and predictable.

Tool Count5/5

With exactly two tools, the set is minimal and perfectly scoped for bidirectional CEP-address lookup. Each tool provides a distinct, necessary function without redundancy.

Completeness5/5

The pair covers both directions of the CEP-address mapping, which is the complete domain for a ViaCEP service. No obvious missing operations.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-brasilapi

    silasrm
    A
    license
    A
    quality
    C
    maintenance
    Exposes the BrasilAPI as MCP tools, enabling AI agents to query Brazilian public data such as CEP, CNPJ, DDD, IBGE, banks, PIX, FIPE, NCM, exchange rates, taxes, weather, CVM information, holidays, ISBN, domains, stock tickers, and TUSS.
    41
    Apache 2.0

  • mcp-cep

    fspjonny
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables querying Brazilian CEP (postal code) addresses via the public ViaCEP API, returning formatted HTML with address details.
    GPL 3.0