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

| Feature | Fonte | Tools | |---------|-------|:-----:| | bacen | Banco Central — Selic, IPCA, câmbio, PIB e +190 séries temporais | 9 | | bndes | BNDES — operações de financiamento, desembolsos, instituições credenciadas | 4 |

Geografia e Estatística

| Feature | Fonte | Tools | |---------|-------|:-----:| | ibge | IBGE — estados, municípios, nomes, agregados estatísticos | 9 |

Legislativo

| Feature | Fonte | Tools | |---------|-------|:-----:| | 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 e Fiscalização

| Feature | Fonte | Tools | |---------|-------|:-----:| | transparencia | Portal da Transparência — contratos, despesas, servidores, sanções | 18 | | tcu | Tribunal de Contas da União — acórdãos, inidôneos, débitos, pautas | 9 | | tce_sp | TCE-SP — despesas e receitas de 645 municípios paulistas | 3 | | tce_rj | TCE-RJ — licitações, contratos, obras, penalidades, concessões | 7 | | tce_rs | TCE-RS — educação, saúde, gestão fiscal (LRF) | 5 | | tce_pe | TCE-PE — licitações, contratos, despesas, fornecedores | 5 | | tce_ce | TCE-CE — licitações, contratos, empenhos | 4 | | tce_es | TCE-ES — licitações, contratos, obras públicas | 4 | | tce_rn | TCE-RN — jurisdicionados, licitações, contratos | 5 | | tce_pi | TCE-PI — prefeituras, despesas, receitas | 5 | | tce_sc | TCE-SC — municípios e unidades gestoras | 2 | | tce_to | TCE-TO — processos, pautas de sessões | 3 |

Judiciário

| Feature | Fonte | Tools | |---------|-------|:-----:| | datajud | DataJud/CNJ — processos judiciais, movimentações | 7 | | jurisprudencia | STF, STJ e TST — acórdãos, súmulas, decisões | 6 |

Eleitoral

| Feature | Fonte | Tools | |---------|-------|:-----:| | tse | TSE — eleições, candidatos, prestação de contas | 15 | | anuncios_eleitorais | Biblioteca de Anúncios da Meta — propaganda eleitoral na internet | 6 |

Meio Ambiente

| Feature | Fonte | Tools | |---------|-------|:-----:| | inpe | INPE — focos de queimadas, desmatamento DETER/PRODES | 4 | | ana | ANA — estações hidrológicas, telemetria, reservatórios | 3 |

Saúde

| Feature | Fonte | Tools | |---------|-------|:-----:| | saude | CNES/DataSUS — estabelecimentos, profissionais, leitos | 10 | | opendatasus | OpenDataSUS — datasets de saúde pública (CKAN) | 7 | | anvisa | ANVISA — bulário, medicamentos, preços CMED, registros | 10 | | denasus | DENASUS — auditorias do SUS | 5 | | imunizacao | SI-PNI — vacinação, calendário, cobertura vacinal, SRAG | 10 | | bps | BPS — preços de medicamentos e dispositivos médicos no SUS | 3 | | farmacia_popular | Farmácia Popular — medicamentos gratuitos, farmácias credenciadas | 8 | | rename | RENAME — medicamentos essenciais do SUS por princípio ativo | 5 |

Segurança Pública

| Feature | Fonte | Tools | |---------|-------|:-----:| | forum_seguranca | Fórum Brasileiro de Segurança Pública — Atlas da Violência, Anuário | 4 |

Compras Públicas

| Feature | Fonte | Tools | |---------|-------|:-----:| | compras | PNCP + ComprasNet/SIASG — licitações, contratos, pregões, CATMAT | 29 | | transferegov | TransfereGov — emendas parlamentares PIX | 5 |

Dados Abertos e Utilidades

| Feature | Fonte | Tools | |---------|-------|:-----:| | brasilapi | BrasilAPI — CEP, CNPJ, DDD, bancos, câmbio, FIPE, PIX | 16 | | dados_abertos | Dados Abertos (dados.gov.br) — catálogo de datasets federais | 4 | | diario_oficial | Querido Diário + DOU — diários oficiais de 5.000+ cidades e da União | 11 | | tabua_mares | Tábua de Marés — previsão de marés para portos do litoral | 7 |

O server raiz também 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 | Opcional | Cadastro gratuito | | DataJud/CNJ | Opcional | Cadastro gratuito | | Anúncios Eleitorais (Meta) | Opcional | Meta Ad Library API | | Todas as outras (36) | Nenhuma chave | — |

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

| Variável | Default | Descrição | |----------|---------|-----------| | TRANSPARENCIA_API_KEY | — | Chave do Portal da Transparência | | DATAJUD_API_KEY | — | Chave do DataJud/CNJ | | META_ACCESS_TOKEN | — | Token da Meta Ad Library API | | 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 | Todas as 39 features e suas 309 tools | | Smart Tools | Meta-tools: planner, batch, discovery | | Adicionando Features | Guia para contribuir com novas APIs | | Configuração | Variáveis de ambiente e opções | | Meta Ad Library API | Referência da API de anúncios eleitorais da Meta | | Code Mode | Discovery programático + sandbox Python (experimental) | | Desenvolvimento | Setup de dev, testes, lint, CI |

Casos de Uso

Exemplos de contextos profissionais onde o mcp-brasil pode ser aplicado:

| Caso de Uso | Descrição | APIs Combinadas | |-------------|-----------|-----------------| | Panorama Econômico | Dashboard econômico com Selic, IPCA, câmbio, PIB | Bacen, IBGE, BNDES, Transparência | | Fiscalização Municipal | Onde vai o dinheiro da sua cidade — 10 TCEs cruzados | TCEs, PNCP, Contratos.gov.br, TransfereGov, IBGE | | Análise Legislativa | Ciclo completo de um PL: Câmara → Senado → DOU → STF | Câmara, Senado, Diário Oficial, DataJud | |