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.