mcp-brasil

MCP Server para 70 fontes de dados públicas brasileiras

533 tools · 131 resources · 102 prompts · 70 features · 15 áreas temáticas

Conecte AI agents (Claude, GPT, Copilot, etc.) a dados governamentais do Brasil — economia, legislação, transparência, judiciário, eleições, meio ambiente, saúde, educação, segurança pública, fiscal subnacional, aviação e mais.

66 APIs não requerem chave · 4 usam chaves gratuitas (cadastro em 1 min)

Quick Start · Fontes de dados · Documentação · Desenvolvimento

Features

• 533 tools em 70 features cobrindo 15 áreas — economia, legislativo, transparência, judiciário, eleitoral, ambiental, saúde, educação, segurança pública, compras públicas, fiscal subnacional, aviação, energia e mais
• Datasets grandes com cache local — SIAPA (~813k imóveis), TSE 2014-2024 (candidatos, bens, votação, redes sociais, FEFC), ANP preços de combustíveis, INEP Censo Escolar e ENEM, ISP-RJ segurança pública, ANAC aeronaves e voos regulares — SQL via DuckDB embedded, opt-in via env
• Cross-referencing com planejar_consulta — cria planos de execução combinando múltiplas APIs (ex: gastos de um deputado + votações + proposições)
• Execução em lote com executar_lote — dispara consultas em paralelo numa única chamada
• Smart discovery — BM25 search transform filtra 533 tools para só mostrar as relevantes ao contexto
• Auto-registry — adicionar uma feature é criar uma pasta; zero configuração manual
• Async everywhere — httpx async + Pydantic v2 + rate limiting com backoff

Quick Start

Instalar

pip install mcp-brasil

uv add mcp-brasil

Claude Desktop

Adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"],
      "env": {
        "TRANSPARENCIA_API_KEY": "sua-chave-aqui",
        "DATAJUD_API_KEY": "sua-chave-aqui",
        "META_ACCESS_TOKEN": "seu-token-aqui"
      }
    }
  }
}

As chaves são opcionais — sem elas, as 36 APIs restantes funcionam normalmente.

VS Code / Cursor

Crie .vscode/mcp.json na raiz do projeto:

{
  "servers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"],
      "env": {
        "TRANSPARENCIA_API_KEY": "sua-chave-aqui",
        "DATAJUD_API_KEY": "sua-chave-aqui",
        "META_ACCESS_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Claude Code

claude mcp add mcp-brasil -- uvx --from mcp-brasil python -m mcp_brasil.server

HTTP (outros clientes)

fastmcp run mcp_brasil.server:mcp --transport http --port 8000
# Server disponível em http://localhost:8000/mcp

Exemplos

Conecte o server e faça perguntas em linguagem natural:

Legislativo: "Quais projetos de lei sobre inteligência artificial tramitaram na Câmara em 2024? Quem foram os autores?"

Econômico: "Qual a tendência da taxa Selic nos últimos 12 meses? Compare com a inflação (IPCA) no mesmo período."

Transparência: "Quais os 10 maiores contratos do governo federal em 2024? Quem são os fornecedores?"

Cross-reference: "Compare os gastos per capita com saúde em São Paulo e Minas Gerais cruzando dados do TCE-SP e IBGE."

Judiciário: "Busque processos sobre licitação irregular no TCU. Quais foram as penalidades aplicadas?"

Eleitoral: "Quais os maiores doadores da campanha do candidato X? Qual o total arrecadado?"

Fontes de dados

Economia e Finanças

Geografia e Estatística

Legislativo e Executivo

Transparência e Fiscalização

Judiciário

Eleitoral

Meio Ambiente

Energia e Infraestrutura

Aviação

Saúde

Segurança Pública

Educação

Compras Públicas

Mercado Financeiro e Notícias

Dados Abertos e Utilidades

Datasets locais (opt-in via env)

Features que baixam CSVs/ZIPs grandes (~100MB–1,6GB) para DuckDB embedded local e expõem SQL via tools canned. Ativadas apenas quando listadas em MCP_BRASIL_DATASETS. Primeira carga: minutos (download + ingest); subsequentes: ms.

Ative com:

# .env
MCP_BRASIL_DATASETS=tse_candidatos,tse_bens,tse_votacao

Ver guia de Datasets locais para detalhes de uso.

O server raiz também expõe 5 meta-tools: listar_features, recomendar_tools, planejar_consulta, executar_lote e listar_datasets_disponiveis.

Chaves de API

Configure via variáveis de ambiente ou .env:

TRANSPARENCIA_API_KEY=sua-chave
DATAJUD_API_KEY=sua-chave
META_ACCESS_TOKEN=seu-token

Configuração

Documentação

Desenvolvimento

git clone https://github.com/jxnxts/mcp-brasil.git
cd mcp-brasil
make dev              # Instalar dependências (prod + dev)
make test             # Rodar todos os testes
make test-feature F=ibge  # Testes de uma feature
make lint             # Lint + format check
make ruff             # Auto-fix lint + format
make types            # mypy strict
make ci               # lint + types + test
make run              # Server stdio
make serve            # Server HTTP :8000
make inspect          # Listar tools/resources/prompts

Arquitetura

O projeto usa Package by Feature com Auto-Registry — cada feature é uma pasta auto-contida:

src/mcp_brasil/
├── server.py              # Auto-registry (nunca editado manualmente)
├── _shared/               # Utilitários compartilhados
│   └── datasets/          # Infra DuckDB local
├── data/                  # 51 features — REST passthrough
│   ├── ibge/
│   │   ├── __init__.py    # FEATURE_META
│   │   ├── server.py      # FastMCP instance
│   │   ├── tools.py       # Lógica das tools
│   │   ├── client.py      # HTTP async
│   │   ├── schemas.py     # Pydantic models
│   │   └── constants.py   # URLs, códigos
│   ├── bacen/
│   └── ...
├── datasets/              # 12 features — cache local DuckDB (opt-in via env)
│   ├── spu_siapa/         # SIAPA 813k imóveis
│   ├── tse_candidatos/    # TSE candidatos 2014-2024
│   └── ...
└── agentes/               # 1 feature — agentes inteligentes
    └── redator/

Três modalidades de feature coexistem:

• data/ — REST passthrough: HTTP async → Pydantic → tool formatada
• datasets/ — DuckDB embedded local: CSVs/ZIPs grandes com SQL, gated por MCP_BRASIL_DATASETS, cache em ~/.cache/mcp-brasil/
• agentes/ — Agentes inteligentes: tools + prompts + resources compondo fluxos complexos (ex: redação oficial)

Para adicionar uma nova feature, basta criar o diretório seguindo a convenção — o registry descobre automaticamente.

Contribuindo

1. Fork o repositório
2. Crie uma feature em src/mcp_brasil/data/{feature}/ ou agentes/{feature}/
3. Exporte FEATURE_META no __init__.py e mcp: FastMCP no server.py
4. Adicione testes em tests/data/{feature}/
5. Rode make ci e abra um PR

Disclaimer

Este projeto integra um número significativo de APIs governamentais brasileiras, muitas com documentação inconsistente ou incompleta. Embora todo esforço tenha sido feito para garantir precisão, alguns endpoints podem retornar resultados inesperados ou ter cobertura parcial de parâmetros.

Este é um projeto open-source da comunidade — se encontrar algo quebrado ou que possa ser melhorado, abra uma issue ou envie um PR. O objetivo é tornar dados públicos brasileiros acessíveis via IA, juntos.

Todos os dados vêm de APIs oficiais do governo brasileiro — o server não gera, modifica ou editorializa nenhum dado.

Licença

MIT

Star History