<div align="center">

<img src="docs/assets/logo.png" alt="mcp-brasil logo" width="100">

mcp-brasil

MCP Server para 36 fontes públicas brasileiras e 1 agente

245 tools · 58 resources · 48 prompts

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 e mais.

33 fontes não requerem chave · 3 usam chaves de API · 1 fonte adicional depende de token Meta

Quick Start · Origem e alterações · Fontes de dados · Casos de Uso · Documentação · Desenvolvimento

</div>

---

Features

• 245 tools em 37 features ativas — economia, legislativo, transparência, controle externo, judiciário, eleitoral, ambiental, saúde, compras públicas, aviação, mercado de capitais, sanções/PEPs, oceanografia e redação oficial
• 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 o catálogo de 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

Origem e alterações

Este projeto foi baixado a partir de, e hoje deve ser lido como uma evolução inspirada por, jxnxts/mcp-brasil. A base original serviu como ponto de partida conceitual para expor APIs públicas brasileiras via MCP/FastMCP, mas esta árvore foi bastante expandida e reorganizada.

Principais alterações feitas nesta versão:

• ampliação do catálogo para 37 features ativas, com 241 tools de features mais 4 meta-tools (listar_features, recomendar_tools, planejar_consulta, executar_lote);
• inclusão de novas fontes como ANAC, ANS, BNDES, CVM, IBAMA, SICONFI, OpenSanctions, Dados Abertos MT, IOMAT-MT e mais TCEs;
• organização por feature com FeatureMeta, server.py, cliente HTTP, schemas e tools isolados;
• auto-discovery em mcp_brasil.data e mcp_brasil.agentes, reduzindo configuração manual ao adicionar uma fonte;
• meta-tools para descoberta, planejamento de consultas complexas e execução em lote;
• suporte a BM25/code-mode para reduzir ruído em clientes que não lidam bem com centenas de tools;
• agente redator para documentos oficiais, separado das fontes de dados.

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",
        "OPENSANCTIONS_API_KEY": "sua-chave-aqui",
        "META_ACCESS_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Sem uma chave configurada, a feature correspondente é ignorada no auto-registry; as demais fontes continuam funcionando 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",
        "OPENSANCTIONS_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

Categoria	Feature	API	Tools
Econômico	ibge	IBGE — estados, municípios, nomes, agregados estatísticos	9
	bacen	Banco Central — Selic, IPCA, câmbio, PIB e +190 séries	10
	bndes	BNDES — operações de financiamento não-automáticas	1
	cvm	CVM — companhias abertas, fundos e processos sancionadores	3
	siconfi	SICONFI/Tesouro — RREO, RGF e contas anuais	3
Legislativo	camara	Câmara dos Deputados — deputados, proposições, votações, despesas	11
	senado	Senado Federal — senadores, matérias, votações, comissões	26
Transparência / Fiscal	transparencia	Portal da Transparência — contratos, despesas, servidores, sanções	19
	tcu	Tribunal de Contas da União — acórdãos, licitantes inidôneos	8
	tce_sp	TCE-SP — despesas e receitas de 645 municípios paulistas	3
	tce_rj	TCE-RJ — licitações, contratos, obras, penalidades	7
	tce_rs	TCE-RS — educação, saúde, gestão fiscal (LRF)	5
	tce_sc	TCE-SC — municípios e unidades gestoras	2
	tce_pe	TCE-PE — licitações, contratos, despesas, fornecedores	5
	tce_ce	TCE-CE — licitações, contratos, empenhos	4
	tce_rn	TCE-RN — jurisdicionados, licitações, contratos	5
	tce_pi	TCE-PI — prefeituras, despesas, receitas	5
	tce_to	TCE-TO — processos, pautas de sessões	3
	dadosabertos_mt	Dados Abertos MT — catálogo CKAN estadual	5
Judiciário	datajud	DataJud/CNJ — processos judiciais, movimentações	7
	jurisprudencia	STF, STJ e TST — acórdãos, súmulas, decisões	6
Eleitoral	tse	TSE — eleições, candidatos, prestação de contas	15
	anuncios_eleitorais	Biblioteca de Anúncios da Meta — anúncios políticos e eleitorais (requer token)	4
Ambiental	inpe	INPE — focos de queimadas e desmatamento	4
	ana	ANA — estações hidrológicas, telemetria, reservatórios	3
	ibama	IBAMA — áreas embargadas e autos de infração	3
Saúde	saude	CNES/DataSUS — estabelecimentos, profissionais, leitos	4
	ans	ANS — operadoras de planos de saúde	1
Aviação	anac	ANAC/RAB — aeronaves registradas no Brasil	1
Oceanografia	tabua_mares	Tábua de Marés — previsão de marés para portos do litoral brasileiro	7
Compras Públicas	compras	PNCP + Compras.gov.br — licitações, contratos, fornecedores, CATMAT, CATSER, pregões e pesquisa de preços	13
Utilidades	brasilapi	BrasilAPI — CEP, CNPJ, DDD, bancos, câmbio, FIPE, PIX	16
	dados_abertos	Dados Abertos (dados.gov.br) — catálogo de datasets	4
	diario_oficial	Querido Diário — diários oficiais de 5.000+ cidades	4
	iomat_mt	Diário Oficial de MT/IOMAT — publicações e edições	5
	transferegov	TransfereGov — emendas parlamentares PIX	5
Compliance	opensanctions	OpenSanctions — sanções internacionais e PEPs	4
Agentes IA	redator	Redator Oficial — ofício, despacho, portaria, parecer, nota técnica	5

Além das tools das features, o server raiz expõe 4 meta-tools: listar_features, recomendar_tools, planejar_consulta e executar_lote.

Chaves de API

API	Obrigatória?	Como obter
Portal da Transparência	Sim para ativar a feature	Cadastro gratuito
DataJud/CNJ	Sim para ativar a feature	Cadastro gratuito
OpenSanctions	Sim para ativar a feature	API keys
Biblioteca de Anúncios da Meta	Sim para ativar a feature anuncios_eleitorais	Meta for Developers
Todas as outras fontes	Nenhuma chave	—

Configure via variáveis de ambiente ou .env:

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

Configuração

Variável	Default	Descrição
TRANSPARENCIA_API_KEY	—	Chave do Portal da Transparência
DATAJUD_API_KEY	—	Chave do DataJud/CNJ
OPENSANCTIONS_API_KEY	—	Chave da API OpenSanctions
META_ACCESS_TOKEN	—	Token da Meta Graph API para anúncios eleitorais
MCP_BRASIL_TOOL_SEARCH	bm25	Modo de discovery: bm25, code_mode ou none
MCP_BRASIL_HTTP_TIMEOUT	30.0	Timeout HTTP em segundos
MCP_BRASIL_HTTP_MAX_RETRIES	3	Máximo de retentativas HTTP

Documentação

Página	Descrição
Quick Start	Instalação e configuração em 2 minutos
Arquitetura	Como o projeto funciona por dentro
Catálogo de Features	Catálogo de features e tools disponíveis
Smart Tools	Meta-tools: planner, batch, discovery
Adicionando Features	Guia para contribuir com novas APIs
Configuração	Variáveis de ambiente e opções
Desenvolvimento	Setup de dev, testes, lint, CI

Casos de Uso

Exemplos detalhados de como usar o mcp-brasil em diferentes contextos profissionais:

Caso de Uso	Descrição	APIs Combinadas
Panorama Econômico	Dashboard econômico com Selic, IPCA, câmbio, PIB	Bacen, IBGE, Transparência
Fiscalização Municipal	Onde vai o dinheiro da sua cidade — 9 TCEs cruzados	TCEs, PNCP, TransfereGov, IBGE
Análise Legislativa	Ciclo completo de um PL: Câmara → Senado → Diário Oficial → STF	Câmara, Senado, Diário Oficial, DataJud
Cientista Político	Fidelidade partidária, coalizões, emendas como poder	Câmara, Senado, TSE, Transparência
Economista	Séries temporais, política fiscal, câmbio, crédito	Bacen (40K+ séries), IBGE
Jornalista Investigativo	Rastrear emendas, licitações dirigidas, fornecedores suspeitos	Transparência, TCEs, TCU, PNCP, TSE
Jornalista — Matérias	Produção de matérias data-driven com dados verificáveis	Bacen, IBGE, Câmara, INPE, TSE
Relatório Parlamentar	Votação + emendas + despesas + financiamento de um parlamentar	Câmara, Senado, TSE, TransfereGov
Políticas Públicas	Avaliar impacto: recursos investidos vs. resultados	TCEs, IBGE, CNES, Transparência, INPE
Redator Oficial	Gerar ofícios, pareceres e notas técnicas com dados reais	Redator + Bacen, Transparência, TCU

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
├── data/                  # Features de consulta a APIs/fontes de dados
│   ├── 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/
│   └── ...
└── agentes/               # Features de agentes inteligentes
    └── redator/

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