mcp-brasil-server

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mcp-brasil-server

Skill by ara.so — MCP Skills collection.

MCP Server providing 533 tools across 70+ Brazilian public data sources including economy (Banco Central, IBGE), legislation (Câmara, Senado), transparency (Portal da Transparência, TCU), judiciary (DataJud, STF), elections (TSE), environment (INPE, IBAMA), health (DataSUS, ANVISA), education (INEP), and more. Most APIs require no authentication; 4 features use free API keys. Includes local dataset caching with DuckDB for large datasets (TSE elections, SPU properties, ANP fuel prices, INEP school census).

由ara.so开发的Skill——MCP Skills合集。

本MCP服务器提供533个工具，覆盖70余个巴西公共数据源，包括经济领域（巴西央行Banco Central、巴西地理统计局IBGE）、立法领域（众议院Câmara、参议院Senado）、透明度领域（透明度门户Portal da Transparência、联邦审计法院TCU）、司法领域（DataJud、联邦最高法院STF）、选举领域（最高选举法院TSE）、环境领域（国家空间研究院INPE、巴西环境与可再生自然资源研究所IBAMA）、健康领域（DataSUS、国家卫生监督局ANVISA）、教育领域（国家教育研究所INEP）等。大多数API无需认证；仅4项功能需要免费API密钥。支持通过DuckDB对大型数据集（TSE选举数据、SPU房产数据、ANP燃油价格、INEP学校普查数据）进行本地缓存。

Installation

安装

pip/uv

bash

pip install mcp-brasil

bash

uv add mcp-brasil

bash

pip install mcp-brasil

bash

uv add mcp-brasil

Claude Desktop

Add to

claude_desktop_config.json

json

{
  "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"
      }
    }
  }
}

Environment variables:

```
TRANSPARENCIA_API_KEY
```
(optional) - Portal da Transparência API key
```
DATAJUD_API_KEY
```
(optional) - DataJud/CNJ API key
```
META_ACCESS_TOKEN
```
(optional) - Meta Graph API token for electoral ads

MCP_BRASIL_DATASETS

(optional) - Comma-separated list of local datasets to enable:

spu_siapa

tse_candidatos

tse_bens

tse_votacao

tse_redes_sociais

tse_fefc

anp_precos

inep_censo_escolar

inep_enem

添加至

claude_desktop_config.json

：

json

{
  "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"
      }
    }
  }
}

环境变量：

```
TRANSPARENCIA_API_KEY
```
（可选）——透明度门户API密钥
```
DATAJUD_API_KEY
```
（可选）——DataJud/CNJ API密钥
```
META_ACCESS_TOKEN
```
（可选）——用于选举广告的Meta Graph API令牌

MCP_BRASIL_DATASETS

（可选）——启用的本地数据集逗号分隔列表：

spu_siapa

tse_candidatos

tse_bens

tse_votacao

tse_redes_sociais

tse_fefc

anp_precos

inep_censo_escolar

inep_enem

VS Code / Cursor

Create

.vscode/mcp.json

json

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

创建

.vscode/mcp.json

：

json

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

Claude Code CLI

bash

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

bash

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

HTTP Mode (for other MCP clients)

HTTP模式（适用于其他MCP客户端）

bash

fastmcp run mcp_brasil.server:mcp --transport http --port 8000

bash

fastmcp run mcp_brasil.server:mcp --transport http --port 8000

Server available at http://localhost:8000/mcp

服务器地址：http://localhost:8000/mcp

undefined

undefined

Key Features

核心功能

533 Tools Across 70 Data Sources

70个数据源，共533个工具

The server auto-discovers features from the

features/

directory. Each feature provides multiple tools:

Economy:
```
bacen
```
(9 tools),
```
bcb_olinda
```
(8),
```
bndes
```
(4),
```
ipeadata
```
(5),
```
b3
```
(6)
Geography:
```
ibge
```
(9 tools for states, municipalities, statistics)
Legislative:
```
camara
```
(11),
```
senado
```
(26),
```
governadores
```
(4)
Transparency:
```
transparencia
```
(54),
```
tcu
```
(9),
```
tce_*
```
(multiple state courts)
Judiciary:
```
datajud
```
(7),
```
jurisprudencia
```
(6)
Electoral:
```
tse
```
(15),
```
anuncios_eleitorais
```
(6)
Environment:
```
inpe
```
(4),
```
ana
```
(3),
```
ibama
```
(4)
Health:
```
saude
```
(10),
```
opendatasus
```
(7),
```
anvisa
```
(10),
```
imunizacao
```
(10)
Education:
```
inep
```
(4),
```
fnde
```
(4)
Security:
```
atlas_violencia
```
(7),
```
sinesp
```
(6)
Utilities:
```
brasilapi
```
(16),
```
dados_abertos
```
(4),
```
diario_oficial
```
(11)

服务器会自动从

features/

目录发现功能。每个功能提供多个工具：

经济类：
```
bacen
```
（9个工具）、
```
bcb_olinda
```
（8个）、
```
bndes
```
（4个）、
```
ipeadata
```
（5个）、
```
b3
```
（6个）
地理类：
```
ibge
```
（9个用于州、市、统计数据的工具）
立法类：
```
camara
```
（11个）、
```
senado
```
（26个）、
```
governadores
```
（4个）
透明度类：
```
transparencia
```
（54个）、
```
tcu
```
（9个）、
```
tce_*
```
（多个州级法院工具）
司法类：
```
datajud
```
（7个）、
```
jurisprudencia
```
（6个）
选举类：
```
tse
```
（15个）、
```
anuncios_eleitorais
```
（6个）
环境类：
```
inpe
```
（4个）、
```
ana
```
（3个）、
```
ibama
```
（4个）
健康类：
```
saude
```
（10个）、
```
opendatasus
```
（7个）、
```
anvisa
```
（10个）、
```
imunizacao
```
（10个）
教育类：
```
inep
```
（4个）、
```
fnde
```
（4个）
安全类：
```
atlas_violencia
```
（7个）、
```
sinesp
```
（6个）
实用工具类：
```
brasilapi
```
（16个）、
```
dados_abertos
```
（4个）、
```
diario_oficial
```
（11个）

Smart Tool Discovery

智能工具发现

The server uses BM25 search to filter tools based on context:

python

undefined

服务器使用BM25搜索根据上下文过滤工具：

python

undefined

When user asks about "inflation and interest rates"

当用户询问“通货膨胀和利率”时

Only economy-related tools (bacen, bcb_olinda) are shown

仅显示经济相关工具（bacen、bcb_olinda）

533 total tools filtered down to ~20 relevant ones

从533个工具筛选出约20个相关工具

undefined

undefined

Cross-Reference Planning

交叉引用规划

Use

planejar_consulta

to create multi-API execution plans:

python

undefined

使用

planejar_consulta

创建多API执行计划：

python

undefined

Tool: planejar_consulta

工具：planejar_consulta

Input: {"objetivo": "Compare spending of deputy X with their voting record on health bills"}

输入：{"objetivo": "比较议员X的支出与他们在医疗法案上的投票记录"}

Returns: Execution plan combining camara tools for expenses + voting + propositions

返回：结合camara支出、投票、提案工具的执行计划

undefined

undefined

Batch Execution

批量执行

Execute multiple queries in parallel:

python

undefined

并行执行多个查询：

python

undefined

Tool: executar_lote

工具：executar_lote

Input: {

输入：{

"consultas": [

{"tool": "bacen_sgs_serie", "params": {"codigo": 433}}, # IPCA

{"tool": "bacen_sgs_serie", "params": {"codigo": 433}}, # IPCA通胀指数

{"tool": "bacen_sgs_serie", "params": {"codigo": 4189}}, # Selic

{"tool": "bacen_sgs_serie", "params": {"codigo": 4189}}, # Selic基准利率

{"tool": "ibge_agregados", "params": {"indicador": "pib"}}

]

}

undefined

undefined

Local Datasets with DuckDB

基于DuckDB的本地数据集

Enable large datasets via

MCP_BRASIL_DATASETS

environment variable:

bash

export MCP_BRASIL_DATASETS="tse_candidatos,tse_votacao,anp_precos"

Available datasets:

```
spu_siapa
```
- 813k federal properties
```
tse_candidatos
```
- 4M+ candidate records (2014-2024)
```
tse_bens
```
- Candidate asset declarations
```
tse_votacao
```
- Vote counts by municipality/zone
```
tse_redes_sociais
```
- Candidate social media URLs
```
tse_fefc
```
- Electoral fund distributions
```
anp_precos
```
- Weekly fuel prices at gas stations
```
inep_censo_escolar
```
- 180k+ schools infrastructure data
```
inep_enem
```
- 3.9M+ ENEM exam records

First load downloads and ingests data (minutes); subsequent queries run in milliseconds.

通过

MCP_BRASIL_DATASETS

环境变量启用大型数据集：

bash

export MCP_BRASIL_DATASETS="tse_candidatos,tse_votacao,anp_precos"

可用数据集：

```
spu_siapa
```
- 81.3万条联邦房产记录
```
tse_candidatos
```
- 400万+候选人记录（2014-2024）
```
tse_bens
```
- 候选人资产申报数据
```
tse_votacao
```
- 按市/选区统计的投票数
```
tse_redes_sociais
```
- 候选人社交媒体链接
```
tse_fefc
```
- 选举资金分配数据
```
anp_precos
```
- 加油站每周燃油价格
```
inep_censo_escolar
```
- 18万+学校基础设施数据
```
inep_enem
```
- 390万+ENEM考试记录

首次加载会下载并导入数据（耗时数分钟）；后续查询仅需毫秒级响应。

Common Usage Patterns

常见使用场景

Query Economic Indicators

查询经济指标

python

undefined

python

undefined

Get Selic rate time series

获取Selic基准利率时间序列

tool: bacen_sgs_serie params: codigo: 432 data_inicio: "2024-01-01" data_fim: "2024-12-31"

Get IPCA inflation

获取IPCA通胀数据

tool: bacen_sgs_serie params: codigo: 433

Get official exchange rate (PTAX)

获取官方汇率（PTAX）

tool: bcb_olinda_ptax params: data_cotacao: "2024-05-15" moeda: "USD"

undefined

tool: bcb_olinda_ptax params: data_cotacao: "2024-05-15" moeda: "USD"

undefined

Search Legislative Data

搜索立法数据

python

undefined

python

undefined

Find bills about AI in the Chamber

在众议院查找关于AI的法案

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"

undefined

tool: senado_materias_buscar params: assunto: "meio ambiente"

undefined

Access Transparency Data

访问透明度数据

python

undefined

python

undefined

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

查询TCU法院裁决

tool: tcu_acordaos params: ano: 2024 palavras_chave: "licitação fraude"

undefined

tool: tcu_acordaos params: ano: 2024 palavras_chave: "licitação fraude"

undefined

Electoral Data Queries

选举数据查询

python

undefined

python

undefined

Search candidates (requires tse_candidatos dataset)

搜索候选人（需启用tse_candidatos数据集）

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)

获取候选人资产（需启用tse_bens数据集）

tool: tse_bens_query params: sql: "SELECT * FROM bens WHERE sq_candidato = '123456' ORDER BY valor DESC"

Electoral ads from Meta

Meta平台选举广告

tool: anuncios_eleitorais_buscar params: eleicao: "2024" candidato: "João Silva"

undefined

tool: anuncios_eleitorais_buscar params: eleicao: "2024" candidato: "João Silva"

undefined

Health and Environment Data

健康与环境数据

python

undefined

python

undefined

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"

undefined

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

undefined

Geographic and Statistical Data

地理与统计数据

python

undefined

python

undefined

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

undefined

tool: ibge_agregados params: indicador: "população" nivel_territorial: "município" localidade: "3550308" # 圣保罗市代码

undefined

Fuel Prices (requires anp_precos dataset)

燃油价格查询（需启用anp_precos数据集）

python

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
  """

python

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
  """

School Census (requires inep_censo_escolar dataset)

学校普查数据（需启用inep_censo_escolar数据集）

python

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
  """

python

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
  """

Resources and Prompts

资源与提示词

The server provides 131 resources and 102 prompts for common tasks:

Resources:

Dataset schemas and metadata
Feature documentation
API endpoint references

Prompts:

"Analyze deputy spending patterns"
"Compare state-level health indicators"
"Track bill progress through legislature"
"Find contract anomalies"

服务器提供131项资源和102个常见任务提示词：

资源：

数据集架构与元数据
功能文档
API端点参考

提示词：

"分析议员支出模式"
"比较各州健康指标"
"追踪法案在立法机构的进展"
"发现合同异常"

Development and Extension

开发与扩展

Adding a New Feature

添加新功能

Create directory:
```
mcp_brasil/features/my_feature/
```
Add
```
tools.py
```
:

python

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()

创建目录：
```
mcp_brasil/features/my_feature/
```
添加
```
tools.py
```
：

python

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()

通过自动发现完成注册（无需额外配置）

Local Development

本地开发

bash

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]"

bash

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

Run server

启动服务器

python -m mcp_brasil.server

Run tests

运行测试

pytest tests/

undefined

pytest tests/

undefined

Rate Limiting

速率限制

All HTTP requests use automatic rate limiting with exponential backoff:

python

undefined

所有HTTP请求自动使用指数退避算法进行速率限制：

python

undefined

Configured in ServerContext

在ServerContext中配置

http = httpx.AsyncClient( timeout=30.0, limits=httpx.Limits(max_keepalive_connections=10, max_connections=20) )

Rate limiting handled automatically per feature

速率限制按功能自动处理

undefined

undefined

Troubleshooting

故障排除

API Keys Not Working

API密钥无法使用

bash

undefined

bash

undefined

Verify environment variables are set

验证环境变量是否已设置

echo $TRANSPARENCIA_API_KEY echo $DATAJUD_API_KEY

Most features work without keys - only 4 require them:

大多数功能无需密钥，仅4项需要：

- transparencia (54 tools)

- transparencia（54个工具）

- datajud (7 tools)

- datajud（7个工具）

- anuncios_eleitorais (6 tools)

- anuncios_eleitorais（6个工具）

- spu_geo (4 tools - uses TRANSPARENCIA_API_KEY)

- spu_geo（4个工具，使用TRANSPARENCIA_API_KEY）

undefined

undefined

Dataset Download Fails

数据集下载失败

bash

undefined

bash

undefined

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

检查磁盘空间（数据集大小为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

undefined

export MCP_BRASIL_DATASETS="tse_candidatos" # 先启用一个

undefined

Too Many Tools Shown

显示工具过多

The BM25 search transform should filter automatically. If you see all 533 tools:

bash

undefined

BM25搜索转换应自动筛选工具。如果显示全部533个工具：

bash

undefined

Check MCP client supports search transforms

检查MCP客户端是否支持搜索转换

Claude Desktop and modern MCP clients do this automatically

Claude Desktop和现代MCP客户端会自动处理

Manually use planejar_consulta to scope your query

手动使用planejar_consulta来限定查询范围

undefined

undefined

HTTP Timeouts

HTTP超时

python

undefined

python

undefined

Increase timeout in ServerContext if needed

必要时在ServerContext中增加超时时间

Default is 30s, some large queries may need more

默认30秒，部分大型查询可能需要更长时间

For dataset queries, ensure dataset is downloaded first

对于数据集查询，确保数据集已下载完成

First query triggers download (minutes), subsequent are instant

首次查询会触发下载（耗时数分钟），后续查询即时响应

undefined

undefined

Invalid SQL Queries on Datasets

数据集SQL查询无效

python

undefined

python

undefined

Get schema first

先获取架构

tool: tse_candidatos_schema # or other *_schema tool

tool: tse_candidatos_schema # 或其他*_schema工具

Then construct SQL based on actual column names

然后根据实际列名构建SQL

Example correct query:

示例正确查询：

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

undefined

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

undefined

API Key Registration

API密钥注册

Portal da Transparência (free):

Visit https://api.portaldatransparencia.gov.br/
Click "Solicitar chave"
Fill form with email
Receive key instantly

DataJud/CNJ (free):

Visit https://datajud-api.cnj.jus.br/
Register account
Generate API key in dashboard

Meta Access Token (free):

Create Facebook App at https://developers.facebook.com/
Get User Access Token
Use for electoral ads library

透明度门户（免费）：

访问https://api.portaldatransparencia.gov.br/
点击“Solicitar chave”
填写邮箱表单
即时获取密钥

DataJud/CNJ（免费）：

访问https://datajud-api.cnj.jus.br/
注册账户
在控制台生成API密钥

Meta访问令牌（免费）：

在https://developers.facebook.com/创建Facebook应用
获取用户访问令牌
用于选举广告库

License and Data Usage

许可证与数据使用

Code: MIT License
Data sources: Each API has its own license/terms (see SOURCES.md in repo)
Acceptable Use: Read ACCEPTABLE_USE.md before commercial/journalistic use
Not official: Independent project, not affiliated with Brazilian government

代码：MIT许可证
数据源：每个API有各自的许可证/条款（见仓库中的SOURCES.md）
可接受使用：商业/新闻用途前请阅读ACCEPTABLE_USE.md
非官方：独立项目，与巴西政府无关

Resources

资源

Repository: https://github.com/Mcp-Brasil/mcp-brasil
PyPI: https://pypi.org/project/mcp-brasil/
Data Sources: See SOURCES.md in repository
Issues: https://github.com/Mcp-Brasil/mcp-brasil/issues

仓库：https://github.com/Mcp-Brasil/mcp-brasil
PyPI：https://pypi.org/project/mcp-brasil/
数据源：见仓库中的SOURCES.md
问题反馈：https://github.com/Mcp-Brasil/mcp-brasil/issues