mcp-brasilapi
# mcp-brasilapi
Servidor [MCP](https://modelcontextprotocol.io) em Python que expõe a
[BrasilAPI](https://brasilapi.com.br/docs) como ferramentas para agentes de IA:
CEP, CNPJ, DDD, IBGE, bancos, PIX, FIPE, NCM, câmbio, taxas, clima (CPTEC),
corretoras/fundos CVM, feriados, ISBN, RegistroBR, tickers B3 e TUSS.
## Instalação
```bash
uv sync
```
## Execução
**stdio** (padrão, para Claude Desktop / clientes locais):
```bash
python -m mcp_brasilapi
# ou
mcp-brasilapi
```
**streamable-http** (para clientes remotos):
```bash
TRANSPORT=http PORT=8000 python -m mcp_brasilapi
```
O endpoint fica disponível em `http://localhost:8000/mcp`.
## Configuração (variáveis de ambiente)
| Var | Default | Descrição |
|-----|---------|-----------|
| `BRASILAPI_BASE_URL` | `https://brasilapi.com.br/api` | URL base da API |
| `TRANSPORT` | `stdio` | `stdio` ou `http`/`streamable-http` |
| `HOST` / `PORT` | `0.0.0.0` / `8000` | Bind do transporte HTTP |
| `BRASILAPI_CACHE_TTL` | — | Sobrescreve o TTL padrão do cache (segundos) |
| `BRASILAPI_CACHE` | `1` | `0` desliga o cache |
| `BRASILAPI_MAX_CONCURRENCY` | `10` | Máx. requisições concorrentes |
| `BRASILAPI_RATE_PER_SEC` | `10` | Máx. requisições por segundo |
## Ferramentas
Cada ferramenta usa prefixo por recurso. **41 tools** em 18 grupos:
| Grupo | Tools |
|-------|-------|
| CEP | `cep__buscar`, `cep__buscar_v2` |
| CNPJ | `cnpj__buscar` |
| DDD | `ddd__buscar` |
| IBGE | `ibge__listar_ufs`, `ibge__buscar_uf`, `ibge__listar_municipios` |
| Bancos | `bancos__listar`, `bancos__buscar` |
| PIX | `pix__listar_participantes` |
| FIPE | `fipe__listar_tabelas`, `fipe__listar_marcas`, `fipe__listar_veiculos`, `fipe__consultar_preco` |
| NCM | `ncm__listar`, `ncm__buscar`, `ncm__pesquisar` |
| Câmbio | `cambio__listar_moedas`, `cambio__consultar_cotacao` |
| Taxas | `taxas__listar`, `taxas__buscar` |
| CPTEC | `cptec__listar_cidades`, `cptec__buscar_cidade`, `cptec__clima_capitais`, `cptec__clima_aeroporto`, `cptec__previsao_cidade`, `cptec__previsao_coordenadas`, `cptec__ondas_cidade` |
| CVM | `corretoras__listar`, `corretoras__buscar`, `fundos__listar`, `fundos__buscar` |
| Feriados | `feriados__listar` |
| ISBN | `isbn__buscar` |
| RegistroBR | `registrobr__consultar` |
| Tickers B3 | `tickers__listar_acoes`, `tickers__listar_fundos` |
| TUSS | `tuss__listar`, `tuss__buscar`, `tuss__pesquisar`, `tuss__autocomplete` |
Veja `docs/SPEC.md` para o mapa de endpoints e o roadmap por fases.
TDQS
Scored across 41 tools
Each tool has a clearly distinct purpose, grouped by domain (e.g., bancos, cep, fipe) with specific actions like buscar, listar, pesquisar. No two tools overlap in functionality; an agent can easily select the correct one.
Tools follow a consistent domain__verb pattern in snake_case (e.g., bancos__buscar, cep__listar). One minor deviation is cep__buscar_v2, which breaks the verb-only pattern but is still understandable.
41 tools is high but justified given the server aggregates many distinct Brazilian public APIs (banks, CEP, CNPJ, weather, FIPE, IBGE, etc.). Each tool serves a specific query, and the number reflects the breadth of available data.
The tool surface covers key CRUD-like operations for each domain (list, get, search) and even includes advanced features like geolocation CEP and wave prediction. Minor gaps exist (e.g., no explicit update/delete for any domain, but these are read-only APIs).