Assistente de CEP com OpenAI + MCP
gabriellambrechtfranco/mcp_server-
Consulte CEPs brasileiros via IA usando MCP e ViaCEP
Ver no GitHubServidor MCP que integra a API ViaCEP com agentes de IA via OpenAI, permitindo consultas de endereços brasileiros através de linguagem natural. Demonstra na prática como o Model Context Protocol padroniza integrações entre aplicações de IA e ferramentas externas, resolvendo o problema de acoplamento N x M.
Instalação
npx convez-ai gabriellambrechtfranco/mcp_server-1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar busca de endereços em chatbots de IA
- Aprender MCP com exemplo real de ferramenta externa
- Demonstrar tool calling do OpenAI em contexto web
Veredito

Projeto educacional bem estruturado que demonstra MCP resolvendo um problema concreto de integração entre IA e APIs REST. Código limpo e documentação clara, ideal para entender como agentes descobrem e executam capacidades externas sem acoplamento direto.
README
A tradução para o português deste README ainda está na fila.
Assistente de CEP com OpenAI + MCP
Mini-laboratorio para o seminario de Servicos Web sobre Model Context Protocol (MCP).
O projeto demonstra uma aplicacao de IA que conversa com a OpenAI e usa um servidor MCP para consultar CEPs brasileiros na API publica ViaCEP.
Ideia
Quando o usuario pergunta por um CEP, a aplicacao envia a conversa para o modelo da OpenAI com uma ferramenta disponivel. Se o modelo decidir que precisa consultar dados externos, a aplicacao roteia a chamada para o servidor MCP cep-tools, que por sua vez consulta a API REST do ViaCEP.
flowchart LR
U["Usuario"]
APP["Chat CLI Node.js"]
OAI["OpenAI"]
MCP["MCP Server cep-tools"]
VIA["API REST ViaCEP"]
U --> APP
APP --> OAI
OAI --> APP
APP --> MCP
MCP --> VIA
VIA --> MCP
MCP --> APP
APP --> OAI
OAI --> APP
APP --> U
O que o MCP Server expoe
- Tool
consultar_cep: recebe um CEP com ou sem hifen e retorna endereco, bairro, cidade, UF, DDD, codigo IBGE e outros campos. - Resource
cep://exemplos: retorna uma lista de CEPs prontos para usar na demonstracao.
Requisitos
- Node.js 20 ou superior
- NPM
- Chave da OpenAI para usar o chat
Instalacao
npm install
Copie o arquivo de ambiente:
copy .env.example .env
Edite .env:
OPENAI_API_KEY=sua_chave
OPENAI_MODEL=gpt-4.1-mini
Voce pode trocar OPENAI_MODEL por outro modelo disponivel na sua conta.
Rodando a demo MCP sem OpenAI
Este comando prova que o servidor MCP esta funcionando:
npm run demo:cep
Ele deve listar a tool consultar_cep, o resource cep://exemplos e consultar um CEP de Passo Fundo.
Rodando o chat com OpenAI
npm run chat
Exemplos de perguntas:
Consulta o CEP 01001-000
Qual cidade e bairro do CEP 99010-000?
Me explica o endereco do CEP 20040-020
Durante a execucao, o chat imprime uma linha como:
[MCP] Chamando tool consultar_cep com argumentos {"cep":"99010-000"}
Essa linha e util para a apresentacao, porque mostra o momento exato em que a IA aciona a ferramenta externa via MCP.
Scripts
npm run build: valida o TypeScript.npm run mcp:cep: sobe apenas o servidor MCP em stdio.npm run demo:cep: conecta em um cliente MCP local e testa tools/resources.npm run chat: inicia o assistente com OpenAI + MCP.
Estrutura
src/
cep.ts Regras de validacao e chamada ao ViaCEP
mcp-server.ts Servidor MCP com tool e resource
mcp-client.ts Cliente MCP usado pela aplicacao
demo-mcp-client.ts Teste isolado do MCP
chat.ts Chat CLI com OpenAI e tool calling
docs/
roteiro-apresentacao.md
slides.md
referencias.md
Relacao com Servicos Web
O projeto usa uma API REST tradicional, o ViaCEP, mas a disponibiliza para uma aplicacao de IA por meio de MCP. Assim, a demo mostra duas camadas importantes:
- REST continua sendo usado para integrar sistemas web.
- MCP padroniza como agentes de IA descobrem e executam capacidades externas.
Pontos para comentar na apresentacao
- MCP resolve o problema de integracoes N x M entre apps de IA e ferramentas externas.
- O host cria um client MCP para conversar com cada server.
- O server MCP expoe primitives como tools, resources e prompts.
- O transporte local usado aqui e stdio.
- A comunicacao logica do protocolo e baseada em JSON-RPC.
- A aplicacao ainda precisa controlar seguranca, validacao, logs e limites de uso.