What is Brazilian Cep Mcp

brazilian-cep-mcp is an MCP (Model Context Protocol) server that provides tools for querying information about Brazilian Postal Codes (CEP). It utilizes the ViaCEP API to obtain detailed address data based on the provided CEP.

Use cases

Use cases include validating user-entered addresses during registration, providing location-based services in applications, and integrating with chatbots or AI systems to enhance customer support with accurate address data.

How to use

To use brazilian-cep-mcp, clone the repository and install the dependencies using npm. Compile the TypeScript code and start the server in development mode or after compilation. You can query a CEP using the ‘consultar-cep’ tool by providing an 8-digit postal code.

Key features

Key features include complete address lookup via CEP, returning information such as street name, neighborhood, city, state, region, DDD, and IBGE code, as well as MCP protocol implementation for integration with AI agents.

Where to use

brazilian-cep-mcp can be used in applications requiring address validation, e-commerce platforms, logistics services, and any system that needs to retrieve detailed address information based on Brazilian postal codes.

brazilian-cep-mcp

Descrição

Este é um servidor MCP (Model Context Protocol) que fornece ferramentas para consulta de informações de Códigos de Endereçamento Postal (CEP) brasileiros. O servidor utiliza a API ViaCEP para obter dados detalhados de endereços a partir do CEP informado.

Funcionalidades

• Consulta de endereços completos através do CEP
• Retorno de informações como logradouro, bairro, cidade, estado, região, DDD e código IBGE
• Implementação do protocolo MCP para integração com agentes de IA

Instalação

# Clone o repositório
git clone https://github.com/guilhermelirio/brazilian-cep-mcp.git
cd brazilian-cep-mcp

# Instale as dependências
npm install

Como usar

Compilação do projeto

Para compilar o código TypeScript:

npm run build

Execução do servidor

Para iniciar o servidor em modo de desenvolvimento:

npm run dev

Para iniciar o servidor após compilação:

npm start

Consultando um CEP

O servidor disponibiliza a ferramenta consultar-cep que aceita um parâmetro:

• cep: Código postal no formato de 8 dígitos numéricos (obrigatório)

Exemplo de uso:

{
  "cep": "01001000"
}

Resposta:

Endereço encontrado:
CEP: 01001-000
Logradouro: Praça da Sé
Complemento: lado ímpar
Bairro: Sé
Cidade: São Paulo
Estado: SP (São Paulo)
Região: Sudeste
DDD: 11
IBGE: 3550308

Tecnologias utilizadas

• TypeScript
• Node.js
• Axios para requisições HTTP
• Zod para validação de esquemas
• SDK do Model Context Protocol

Configuração Smithery

Este projeto está configurado para funcionar com a plataforma Smithery.ai, que facilita a distribuição e execução de servidores MCP.

Estrutura do projeto

brazilian-cep-mcp/
├── src/
│   └── index.ts       # Código-fonte principal
├── dist/              # Código compilado
├── node_modules/      # Dependências
├── smithery.yaml      # Configuração do Smithery
├── package.json       # Configuração do projeto
├── tsconfig.json      # Configuração do TypeScript
└── README.md          # Este arquivo

Autor

Guilherme Lirio Tomasi de Oliveira

Licença

Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para mais detalhes.

Contribuições

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou enviar pull requests.