pip install mcp-brasil

uv add mcp-brasil

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"],
      "env": {
        "TRANSPARENCIA_API_KEY": "your-transparencia-key",
        "DATAJUD_API_KEY": "your-datajud-key",
        "META_ACCESS_TOKEN": "your-meta-token",
        "MCP_BRASIL_DATASETS": "tse_candidatos,anp_precos"
      }
    }
  }
}

{
  "servers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"],
      "env": {
        "TRANSPARENCIA_API_KEY": "your-key-here"
      }
    }
  }
}

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

fastmcp run mcp_brasil.server:mcp --transport http --port 8000
# Server available at http://localhost:8000/mcp

# When user asks about "inflation and interest rates"
# Only economy-related tools (bacen, bcb_olinda) are shown
# 533 total tools filtered down to ~20 relevant ones

# Tool: planejar_consulta
# Input: {"objetivo": "Compare spending of deputy X with their voting record on health bills"}
# Returns: Execution plan combining camara tools for expenses + voting + propositions

# Tool: executar_lote
# Input: {
#   "consultas": [
#     {"tool": "bacen_sgs_serie", "params": {"codigo": 433}},  # IPCA
#     {"tool": "bacen_sgs_serie", "params": {"codigo": 4189}}, # Selic
#     {"tool": "ibge_agregados", "params": {"indicador": "pib"}}
#   ]
# }

export MCP_BRASIL_DATASETS="tse_candidatos,tse_votacao,anp_precos"

# Get Selic rate time series
tool: bacen_sgs_serie
params:
  codigo: 432
  data_inicio: "2024-01-01"
  data_fim: "2024-12-31"

# Get IPCA inflation
tool: bacen_sgs_serie
params:
  codigo: 433
  
# Get official exchange rate (PTAX)
tool: bcb_olinda_ptax
params:
  data_cotacao: "2024-05-15"
  moeda: "USD"

# Find bills about AI in the Chamber
tool: camara_proposicoes_buscar
params:
  keywords: "inteligência artificial"
  ano: 2024

# Get deputy expenses
tool: camara_deputados_despesas
params:
  deputado_id: "204554"
  mes: 5
  ano: 2024

# Search Senate matters
tool: senado_materias_buscar
params:
  assunto: "meio ambiente"

# Search federal contracts
tool: transparencia_contratos
params:
  data_inicio: "2024-01-01"
  data_fim: "2024-12-31"
  valor_minimo: 1000000

# Get civil servant salaries
tool: transparencia_servidores
params:
  orgao: "Ministério da Saúde"
  mes: 5
  ano: 2024

# Query TCU court decisions
tool: tcu_acordaos
params:
  ano: 2024
  palavras_chave: "licitação fraude"

# Search candidates (requires tse_candidatos dataset)
tool: tse_candidatos_query
params:
  sql: "SELECT * FROM candidatos WHERE ano_eleicao = 2024 AND uf = 'SP' LIMIT 100"

# Get candidate assets (requires tse_bens dataset)
tool: tse_bens_query
params:
  sql: "SELECT * FROM bens WHERE sq_candidato = '123456' ORDER BY valor DESC"

# Electoral ads from Meta
tool: anuncios_eleitorais_buscar
params:
  eleicao: "2024"
  candidato: "João Silva"

# Search health facilities
tool: saude_cnes_estabelecimentos
params:
  municipio: "São Paulo"
  tipo: "Hospital Geral"

# Get vaccination coverage
tool: imunizacao_cobertura_vacinal
params:
  uf: "SP"
  ano: 2024

# Query wildfire hotspots
tool: inpe_focos_queimadas
params:
  data_inicio: "2024-08-01"
  data_fim: "2024-08-31"
  bioma: "Amazônia"

# List municipalities in a state
tool: ibge_municipios
params:
  uf: "SP"

# Get statistical aggregates
tool: ibge_agregados
params:
  indicador: "população"
  nivel_territorial: "município"
  localidade: "3550308"  # São Paulo city code

tool: anp_precos_query
params:
  sql: """
    SELECT municipio, avg(preco_venda) as preco_medio
    FROM precos_gasolina
    WHERE uf = 'SP' AND data_coleta >= '2024-01-01'
    GROUP BY municipio
    ORDER BY preco_medio DESC
    LIMIT 10
  """

tool: inep_censo_query
params:
  sql: """
    SELECT uf, count(*) as total_escolas
    FROM escolas
    WHERE tem_internet = 1 AND tem_biblioteca = 1
    GROUP BY uf
    ORDER BY total_escolas DESC
  """

from mcp_brasil.core import ServerContext
from pydantic import BaseModel, Field

class MyToolInput(BaseModel):
    param1: str = Field(description="Parameter description")
    param2: int = Field(default=10)

async def my_tool(context: ServerContext, params: MyToolInput):
    """Tool description for AI agent."""
    async with context.http.get(
        f"https://api.example.gov.br/endpoint",
        params={"q": params.param1, "limit": params.param2}
    ) as response:
        return await response.json()

git clone https://github.com/Mcp-Brasil/mcp-brasil.git
cd mcp-brasil
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv pip install -e ".[dev]"

# Run server
python -m mcp_brasil.server

# Run tests
pytest tests/

# Configured in ServerContext
http = httpx.AsyncClient(
    timeout=30.0,
    limits=httpx.Limits(max_keepalive_connections=10, max_connections=20)
)
# Rate limiting handled automatically per feature

# Verify environment variables are set
echo $TRANSPARENCIA_API_KEY
echo $DATAJUD_API_KEY

# Most features work without keys - only 4 require them:
# - transparencia (54 tools)
# - datajud (7 tools)
# - anuncios_eleitorais (6 tools)
# - spu_geo (4 tools - uses TRANSPARENCIA_API_KEY)

# Check disk space (datasets can be 100MB-1.6GB)
df -h

# Clear cache and retry
rm -rf ~/.mcp_brasil/cache/

# Enable specific datasets only
export MCP_BRASIL_DATASETS="tse_candidatos"  # Start with one

# Check MCP client supports search transforms
# Claude Desktop and modern MCP clients do this automatically

# Manually use planejar_consulta to scope your query

# Increase timeout in ServerContext if needed
# Default is 30s, some large queries may need more

# For dataset queries, ensure dataset is downloaded first
# First query triggers download (minutes), subsequent are instant

# Get schema first
tool: tse_candidatos_schema  # or other *_schema tool
# Then construct SQL based on actual column names

# Example correct query:
tool: tse_candidatos_query
params:
  sql: "SELECT nm_candidato, sg_partido FROM candidatos WHERE ano_eleicao = 2024 LIMIT 10"