MCP Brasil API
Plugando a Brasil API em todos os LLMs através do Model Context Protocol
Visão Geral
MCP Brasil API é um projeto open source que disponibiliza dados da Brasil API através do Model Context Protocol (MCP). Funcionando como um adaptador universal (similar a uma porta USB-C para integrações de IA), este projeto transforma endpoints de dados brasileiros em serviços MCP padronizados, facilitando o acesso a informações locais por assistentes de IA, LLMs e aplicações que utilizam o padrão MCP.
Recursos Disponíveis
- Consulta de CEP: Obtenha informações detalhadas de endereços a partir de um CEP
- Consulta de CNPJ: Recupere dados cadastrais de empresas a partir de um CNPJ
- Consulta de DDD: Consulte estado e cidades atendidas por um DDD brasileiro
- Consulta de Cambio: Consulte o cambio internacional pareado com o Real
- Consulta de Bancos: Consulte informações dos bancos através do nome ou codigo bancário
Por que MCP?
Com a crescente demanda por integrações entre LLMs e dados reais, o Model Context Protocol (MCP) oferece:
- Integração Padronizada: Conecte diversos dados e serviços com um único protocolo
- Escalabilidade: Adicione ou substitua servidores MCP sem alterar a lógica do cliente
- Segurança e Eficiência: Gerencie integrações com melhores práticas de segurança e desempenho
- Flexibilidade: Permite expandir facilmente para novos endpoints da Brasil API conforme necessário
Instalação
# Instale via pip
pip install mcp-brasil-api
# Ou clone o repositório
git clone https://github.com/lucianfialho/mcp-brasil-api
cd mcp-brasil-api
pip install -e .
Configuração
Crie um arquivo .env baseado no .env.example com as seguintes configurações:
API_BASE_URL=https://brasilapi.com.br/api
USER_AGENT=brasil-api/1.0
Uso
Executando o servidor MCP
# Iniciar o servidor
brasil-api-mcp
Configuração com Smithery
O projeto inclui configuração para Smithery, permitindo inicialização rápida:
# Configuração em smithery.yaml
api_base_url: "https://brasilapi.com.br/api"
user_agent: "brasil-api/1.0"
Exemplos de uso com cliente MCP
from mcp.client import McpClient
# Conecte ao servidor MCP Brasil API
client = McpClient("http://localhost:8000")
# Liste as ferramentas disponíveis
tools = client.list_tools()
print(tools)
# Consulte um CEP
cep_info = client.invoke_tool("consultar_cep", "01001-000")
print(cep_info)
# Consulte um CNPJ
cnpj_info = client.invoke_tool("consultar_cnpj", "00.000.000/0001-91")
print(cnpj_info)
# Consulte um DDD
ddd_info = client.invoke_tool("consultar_ddd", "11")
print(ddd_info)
# Consulte um feriados
feriados_info = client.invoke_tool("consultar_feriados", "1989")
print(feriados_info)
# Consulte cotação de moedas comparadas ao Real
cambio_info = client.invoke_tool("consultar_cambio", {"moeda": "USD"}, {"data": "2025-05-02"})
print(cambio_info)
# Consulte cotação de moedas comparadas ao Real
cambio_info = client.invoke_tool("consultar_cambio_info", "USD", "2025-05-02")
print(cambio_info)
# Consulte informações bancárias
banco_info = client.invoke_tool("consultar_banco_info", "1")
print(banco_info)
# Consulte os feriados de um ano
feriados_info = client.invoke_tool("consultar_feriados", "2025")
print(feriados_info)
Integração com LLMs (Claude, ChatGPT, etc.)
from anthropic import Anthropic
from mcp.client import McpClient
# Configure cliente MCP
mcp_client = McpClient("http://localhost:8000")
tools = mcp_client.list_tools()
# Configure o cliente Claude com as ferramentas do MCP
anthropic = Anthropic()
response = anthropic.messages.create(
model="claude-3-5-sonnet-20240229",
max_tokens=1000,
temperature=0,
system="Você tem acesso a dados brasileiros via MCP.",
messages=[{
"role": "user",
"content": "Encontre informações sobre o CEP 01001-000"
}],
tools=tools # Registra as ferramentas do MCP Brasil API
)
Estrutura do Projeto
mcp-brasil-api/
├── src/
│ ├── tools/ # Implementações das ferramentas MCP
│ │ ├── cep.py # Ferramenta para consulta de CEP
│ │ └── cnpj.py # Ferramenta para consulta de CNPJ
│ ├── utils/ # Funções utilitárias
│ │ ├── api.py # Cliente HTTP para Brasil API
│ │ ├── formatters.py # Formatação de dados
│ │ └── validators.py # Validação de dados
│ └── config.py # Configurações da aplicação
├── server.py # Servidor MCP principal
├── Dockerfile # Containerização
├── pyproject.toml # Configuração do pacote Python
└── smithery.yaml # Configuração para Smithery
Roadmap
- Consulta de CEP
- Consulta de CNPJ
- Consulta de DDD
- Suporte a câmbio
- Suporte a bancos e instituições financeiras
- Suporte a feriados nacionais
- Taxas e índices econômicos
- Cotações de moedas
🤝 Contribuições
Contribuições são bem-vindas! Por favor, leia nosso guia de contribuição antes de enviar pull requests.
- Faça um fork do projeto
- Crie sua branch de recurso (
git checkout -b feature/novo-recurso) - Commit suas mudanças (
git commit -m 'Adiciona novo recurso') - Push para a branch (
git push origin feature/novo-recurso) - Abra um Pull Request
📄 Licença
Este projeto está licenciado sob a licença MIT - veja o arquivo LICENSE para detalhes.
🙏 Agradecimentos
- Brasil API por fornecer os dados públicos
- MCP (Model Context Protocol) por padronizar a comunicação entre modelos e fontes de dados
Metadata
Release files for iflow-mcp_lucianfialho-mcp-brasil-api 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_lucianfialho_mcp_brasil_api-0.1.2.tar.gz | 16.7 kB | Without provenance | Details for iflow_mcp_lucianfialho_mcp_brasil_api-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_lucianfialho_mcp_brasil_api-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_lucianfialho_mcp_brasil_api-0.1.2-py3-none-any.whl |
Total release size: 34.9 kB
Release files / iflow_mcp_lucianfialho_mcp_brasil_api-0.1.2.tar.gz
| Download URL | iflow_mcp_lucianfialho_mcp_brasil_api-0.1.2.tar.gz |
|---|---|
| Size | 16.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
71a61da99d600a92cf0a22fbcb182ca9bd8ad4471aa16246caf946b72c555c36
|
|
BLAKE2b-256 checksum How to use checksums |
fcb4044431a179dc72845b6f8ac21cd62e8d90e4f032755a3f726480b4879040
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_lucianfialho_mcp_brasil_api-0.1.2-py3-none-any.whl
| Download URL | iflow_mcp_lucianfialho_mcp_brasil_api-0.1.2-py3-none-any.whl |
|---|---|
| Size | 18.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4bd1698be8f6d1f620f17cd1f6e4c7d59b7294b5f1f99d5cfb0addb67893432c
|
|
BLAKE2b-256 checksum How to use checksums |
a178228e33e1fb386031872ea64efff03f45a04b8555c0c2b83fa0962a58ab71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_lucianfialho-mcp-brasil-api 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.