mcp-brasil-public-apis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

mcp-brasil: MCP Server for 28 Brazilian Public APIs

mcp-brasil：面向28个巴西公共API的MCP Server

Skill by ara.so — Daily 2026 Skills collection.

mcp-brasil

is a Model Context Protocol (MCP) server that exposes 213 tools, 55 resources, and 45 prompts across 28 Brazilian public APIs — letting AI agents (Claude, GPT, Copilot, Cursor, etc.) query government data in natural language. 26 APIs require no key; only 2 need free registrations.

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

mcp-brasil

是一款Model Context Protocol (MCP)服务器，通过28个巴西公共API对外提供213个工具、55种资源和45个提示词——支持AI Agent（Claude、GPT、Copilot、Cursor等）以自然语言查询政府数据。其中26个API无需密钥，仅2个需要免费注册获取密钥。

Installation

安装

bash

undefined

bash

undefined

pip

pip方式

pip install mcp-brasil

uv (recommended)

uv方式（推荐）

uv add mcp-brasil

---

uv add mcp-brasil

---

Quick Setup by Client

按客户端快速配置

Claude Desktop

Add to

~/Library/Application Support/Claude/claude_desktop_config.json

(macOS) or

%APPDATA%\Claude\claude_desktop_config.json

(Windows):

json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"],
      "env": {
        "TRANSPARENCIA_API_KEY": "$TRANSPARENCIA_API_KEY",
        "DATAJUD_API_KEY": "$DATAJUD_API_KEY"
      }
    }
  }
}

将以下内容添加到

~/Library/Application Support/Claude/claude_desktop_config.json

（macOS）或

%APPDATA%\Claude\claude_desktop_config.json

（Windows）：

json

{
  "mcpServers": {
    "mcp-brasil": {
      "command": "uvx",
      "args": ["--from", "mcp-brasil", "python", "-m", "mcp_brasil.server"],
      "env": {
        "TRANSPARENCIA_API_KEY": "$TRANSPARENCIA_API_KEY",
        "DATAJUD_API_KEY": "$DATAJUD_API_KEY"
      }
    }
  }
}

VS Code / Cursor

Create

.vscode/mcp.json

in your project root:

json

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

在项目根目录创建

.vscode/mcp.json

文件：

json

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

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 Transport (other clients)

HTTP传输（其他客户端）

bash

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

bash

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

Server at http://localhost:8000/mcp

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

---

---

Environment Variables

环境变量

Create a

.env

file or export in your shell:

bash

undefined

创建

.env

文件或在Shell中导出变量：

bash

undefined

Optional — 26 other APIs work without any keys

可选——其余26个API无需密钥即可使用

TRANSPARENCIA_API_KEY=your_key_here # https://portaldatransparencia.gov.br/api-de-dados/cadastrar-email DATAJUD_API_KEY=your_key_here # https://datajud-wiki.cnj.jus.br/api-publica/acesso

TRANSPARENCIA_API_KEY=your_key_here # 注册地址：https://portaldatransparencia.gov.br/api-de-dados/cadastrar-email DATAJUD_API_KEY=your_key_here # 注册地址：https://datajud-wiki.cnj.jus.br/api-publica/acesso

Tuning

调优参数

MCP_BRASIL_TOOL_SEARCH=bm25 # bm25 | code_mode | none (default: bm25) MCP_BRASIL_HTTP_TIMEOUT=30.0 # seconds MCP_BRASIL_HTTP_MAX_RETRIES=3

---

MCP_BRASIL_TOOL_SEARCH=bm25 # 可选值：bm25 | code_mode | none（默认值：bm25） MCP_BRASIL_HTTP_TIMEOUT=30.0 # 超时时间（秒） MCP_BRASIL_HTTP_MAX_RETRIES=3

---

API Coverage (28 Features, 213 Tools)

API覆盖范围（28类功能，213个工具）

Category	Feature Key	API	Tools
Economic	`ibge`	IBGE — states, municipalities, statistics	9
Economic	`bacen`	Banco Central — Selic, IPCA, FX, PIB, 190+ series	9
Legislative	`camara`	Câmara dos Deputados — deputies, bills, votes, expenses	10
Legislative	`senado`	Senado Federal — senators, bills, votes, committees	26
Transparency	`transparencia`	Portal da Transparência — contracts, spending, sanctions	18
Transparency	`tcu`	TCU — rulings, ineligible bidders	8
TCE (states)	`tce_sp/rj/rs/sc/pe/ce/rn/pi/to`	9 State audit courts	39
Judiciary	`datajud`	DataJud/CNJ — court cases, movements	7
Judiciary	`jurisprudencia`	STF, STJ, TST — rulings, precedents	6
Electoral	`tse`	TSE — elections, candidates, campaign finance	15
Environment	`inpe`	INPE — wildfires, deforestation	4
Environment	`ana`	ANA — hydrological stations, reservoirs	3
Health	`saude`	CNES/DataSUS — facilities, professionals, beds	4
Oceanography	`tabua_mares`	Tide tables for Brazilian ports	7
Procurement	`pncp`	PNCP — public contracts (Lei 14.133/2021)	6
Procurement	`dadosabertos`	ComprasNet/SIASG	8
Utilities	`brasilapi`	CEP, CNPJ, DDD, banks, FX, FIPE, PIX	16
Utilities	`dados_abertos`	dados.gov.br — dataset catalog	4
Utilities	`diario_oficial`	Official gazettes from 5,000+ cities	4
Utilities	`transferegov`	Parliamentary PIX transfers	5
AI Agent	`redator`	Draft official documents with real data	5

分类	功能标识	API	工具数量
经济	`ibge`	IBGE——州、市、统计数据	9
经济	`bacen`	巴西中央银行——Selic利率、IPCA指数、汇率、GDP等190+系列数据	9
立法	`camara`	众议院——众议员、法案、投票、开支	10
立法	`senado`	联邦参议院——参议员、法案、投票、委员会	26
透明度	`transparencia`	透明度门户——合同、支出、处罚	18
透明度	`tcu`	联邦审计法院——裁决、不合格投标人	8
州审计法院	`tce_sp/rj/rs/sc/pe/ce/rn/pi/to`	9个州级审计法院	39
司法	`datajud`	DataJud/CNJ——案件、动态	7
司法	`jurisprudencia`	联邦最高法院、高等法院、劳动最高法院——裁决、判例	6
选举	`tse`	最高选举法院——选举、候选人、竞选资金	15
环境	`inpe`	国家空间研究院——野火、森林砍伐	4
环境	`ana`	国家水资源局——水文站、水库	3
健康	`saude`	CNES/DataSUS——医疗机构、专业人员、床位	4
海洋学	`tabua_mares`	巴西港口潮汐表	7
采购	`pncp`	PNCP——公共合同（依据第14.133/2021号法律）	6
采购	`dadosabertos`	ComprasNet/SIASG系统	8
实用工具	`brasilapi`	CEP、CNPJ、DDD、银行、汇率、FIPE、PIX	16
实用工具	`dados_abertos`	dados.gov.br——数据集目录	4
实用工具	`diario_oficial`	5000+城市的官方公报	4
实用工具	`transferegov`	议会PIX转账	5
AI Agent	`redator`	使用真实数据起草官方文件	5

Meta-Tools (Root Server)

元工具（根服务器）

Four special tools are always available regardless of feature:

Tool	Description
`listar_features`	List all 28 features with descriptions
`recomendar_tools`	BM25 search — get relevant tools for a query
`planejar_consulta`	Build multi-API execution plan for a complex query
`executar_lote`	Run multiple tool calls in parallel in one request

无论启用哪些功能，以下四个特殊工具始终可用：

工具	描述
`listar_features`	列出所有28类功能及其描述
`recomendar_tools`	BM25搜索——获取与查询相关的工具
`planejar_consulta`	为复杂查询构建多API执行计划
`executar_lote`	在一次请求中并行运行多个工具调用

Development Commands

开发命令

bash

git clone https://github.com/jxnxts/mcp-brasil.git
cd mcp-brasil

make dev              # Install all dependencies (prod + dev)
make test             # Run all tests
make test-feature F=ibge   # Test a single feature
make lint             # Lint + format check
make ruff             # Auto-fix lint + format
make types            # mypy strict mode
make ci               # lint + types + test (full CI)
make run              # Start server (stdio transport)
make serve            # Start server (HTTP :8000)
make inspect          # List all tools/resources/prompts

bash

git clone https://github.com/jxnxts/mcp-brasil.git
cd mcp-brasil

make dev              # 安装所有依赖（生产+开发）
make test             # 运行所有测试
make test-feature F=ibge   # 测试单个功能
make lint             # 代码检查+格式校验
make ruff             # 自动修复代码检查+格式问题
make types            # mypy严格模式检查
make ci               # 代码检查+类型检查+测试（完整CI流程）
make run              # 启动服务器（stdio传输）
make serve            # 启动服务器（HTTP端口8000）
make inspect          # 列出所有工具/资源/提示词

Architecture: Package by Feature + Auto-Registry

架构：按功能打包+自动注册

src/mcp_brasil/
├── server.py              # Auto-discovers features — never edit manually
├── _shared/               # Shared HTTP client, rate limiting, BM25
├── data/                  # 27 API features
│   ├── ibge/
│   │   ├── __init__.py    # exports FEATURE_META
│   │   ├── server.py      # FastMCP instance (exports `mcp`)
│   │   ├── tools.py       # Tool implementations
│   │   ├── client.py      # Async HTTP via httpx
│   │   ├── schemas.py     # Pydantic v2 models
│   │   └── constants.py   # Base URLs, codes
│   ├── bacen/
│   └── ...
└── agentes/               # Intelligent agent features
    └── redator/

Auto-registry: The root

server.py

scans for

FEATURE_META

__init__.py

and

mcp: FastMCP

server.py

— no manual registration needed.

src/mcp_brasil/
├── server.py              # 自动发现功能——请勿手动编辑
├── _shared/               # 共享HTTP客户端、速率限制、BM25
├── data/                  # 27个API功能模块
│   ├── ibge/
│   │   ├── __init__.py    # 导出FEATURE_META
│   │   ├── server.py      # FastMCP实例（导出`mcp`）
│   │   ├── tools.py       # 工具实现
│   │   ├── client.py      # 基于httpx的异步HTTP客户端
│   │   ├── schemas.py     # Pydantic v2模型
│   │   └── constants.py   # 基础URL、编码
│   ├── bacen/
│   └── ...
└── agentes/               # 智能Agent功能模块
    └── redator/

自动注册：根目录的

server.py

会扫描

__init__.py

中的

FEATURE_META

和

server.py

中的

mcp: FastMCP

实例——无需手动注册。

Adding a New Feature

添加新功能

bash

mkdir src/mcp_brasil/data/myfeature
touch src/mcp_brasil/data/myfeature/{__init__.py,server.py,tools.py,client.py,schemas.py,constants.py}

bash

mkdir src/mcp_brasil/data/myfeature
touch src/mcp_brasil/data/myfeature/{__init__.py,server.py,tools.py,client.py,schemas.py,constants.py}

__init__.py

— Required export

__init__.py

——必须导出

python

from mcp_brasil._shared.types import FeatureMeta

FEATURE_META = FeatureMeta(
    name="myfeature",
    description="Short description of the API",
    tags=["category"],
    requires_key=False,
)

python

from mcp_brasil._shared.types import FeatureMeta

FEATURE_META = FeatureMeta(
    name="myfeature",
    description="Short description of the API",
    tags=["category"],
    requires_key=False,
)

server.py

— Required export

server.py

——必须导出

python

from fastmcp import FastMCP
from .tools import register_tools

mcp = FastMCP("myfeature")
register_tools(mcp)

python

from fastmcp import FastMCP
from .tools import register_tools

mcp = FastMCP("myfeature")
register_tools(mcp)

client.py

— Async HTTP pattern

client.py

——异步HTTP模式

python

import httpx
from mcp_brasil._shared.http import get_client

BASE_URL = "https://api.example.gov.br"

async def fetch_data(endpoint: str, params: dict) -> dict:
    async with get_client() as client:
        response = await client.get(f"{BASE_URL}/{endpoint}", params=params)
        response.raise_for_status()
        return response.json()

python

import httpx
from mcp_brasil._shared.http import get_client

BASE_URL = "https://api.example.gov.br"

async def fetch_data(endpoint: str, params: dict) -> dict:
    async with get_client() as client:
        response = await client.get(f"{BASE_URL}/{endpoint}", params=params)
        response.raise_for_status()
        return response.json()

schemas.py

— Pydantic v2 models

schemas.py

——Pydantic v2模型

python

from pydantic import BaseModel, Field
from typing import Optional

class MyResult(BaseModel):
    id: str
    name: str
    value: Optional[float] = Field(None, description="Numeric value")

python

from pydantic import BaseModel, Field
from typing import Optional

class MyResult(BaseModel):
    id: str
    name: str
    value: Optional[float] = Field(None, description="Numeric value")

tools.py

— Tool registration

tools.py

——工具注册

python

from fastmcp import FastMCP
from .client import fetch_data
from .schemas import MyResult

def register_tools(mcp: FastMCP) -> None:

    @mcp.tool(description="Busca dados do endpoint X")
    async def buscar_dados(
        codigo: str,
        ano: int = 2024,
    ) -> list[MyResult]:
        """Retorna dados do endpoint X para o código fornecido."""
        raw = await fetch_data("endpoint-x", {"codigo": codigo, "ano": ano})
        return [MyResult(**item) for item in raw.get("data", [])]

python

from fastmcp import FastMCP
from .client import fetch_data
from .schemas import MyResult

def register_tools(mcp: FastMCP) -> None:

    @mcp.tool(description="Busca dados do endpoint X")
    async def buscar_dados(
        codigo: str,
        ano: int = 2024,
    ) -> list[MyResult]:
        """Retorna dados do endpoint X para o código fornecido."""
        raw = await fetch_data("endpoint-x", {"codigo": codigo, "ano": ano})
        return [MyResult(**item) for item in raw.get("data", [])]

tests/data/myfeature/test_tools.py

— Test pattern

tests/data/myfeature/test_tools.py

——测试模式

python

import pytest
from unittest.mock import AsyncMock, patch
from mcp_brasil.data.myfeature.tools import register_tools
from fastmcp import FastMCP

@pytest.fixture
def mcp():
    server = FastMCP("test-myfeature")
    register_tools(server)
    return server

@pytest.mark.asyncio
async def test_buscar_dados(mcp):
    mock_response = {"data": [{"id": "001", "name": "Test", "value": 42.0}]}
    with patch("mcp_brasil.data.myfeature.client.fetch_data", new_callable=AsyncMock) as mock:
        mock.return_value = mock_response
        # call via mcp tool invocation or directly
        from mcp_brasil.data.myfeature.tools import buscar_dados
        result = await buscar_dados(codigo="001")
        assert len(result) == 1
        assert result[0].name == "Test"

python

import pytest
from unittest.mock import AsyncMock, patch
from mcp_brasil.data.myfeature.tools import register_tools
from fastmcp import FastMCP

@pytest.fixture
def mcp():
    server = FastMCP("test-myfeature")
    register_tools(server)
    return server

@pytest.mark.asyncio
async def test_buscar_dados(mcp):
    mock_response = {"data": [{"id": "001", "name": "Test", "value": 42.0}]}
    with patch("mcp_brasil.data.myfeature.client.fetch_data", new_callable=AsyncMock) as mock:
        mock.return_value = mock_response
        # 通过mcp工具调用或直接调用
        from mcp_brasil.data.myfeature.tools import buscar_dados
        result = await buscar_dados(codigo="001")
        assert len(result) == 1
        assert result[0].name == "Test"

Common Usage Patterns

常见使用模式

Pattern 1: Cross-reference with

planejar_consulta

模式1：使用

planejar_consulta

进行跨API关联

Ask the agent to plan a multi-API query:

"Crie um plano de consulta para analisar o deputado federal João Silva:
gastos, votações, proposições e financiamento de campanha."

The

planejar_consulta

meta-tool returns a structured execution plan combining

camara

tse

, and

transparencia

tools.

让Agent规划多API查询：

"创建一个查询计划，用于分析联邦众议员若昂·席尔瓦的支出、投票记录、提案及竞选资金情况。"

planejar_consulta

元工具会返回一个结构化执行计划，整合

camara

、

tse

和

transparencia

工具。

Pattern 2: Parallel execution with

executar_lote

模式2：使用

executar_lote

进行并行执行

"Execute em paralelo: taxa Selic atual, IPCA dos últimos 12 meses, 
e câmbio USD/BRL de hoje."

executar_lote

fires all three

bacen

tool calls concurrently.

"并行执行：当前Selic利率、过去12个月的IPCA指数，以及今日美元/巴西雷亚尔汇率。"

executar_lote

会同时调用三个

bacen

工具。

Pattern 3: Smart discovery with

recomendar_tools

模式3：使用

recomendar_tools

进行智能发现

"Quais tools devo usar para investigar contratos suspeitos em licitações municipais?"

BM25 search filters the 213 tools to return only relevant ones (e.g.,

tce_sp

pncp

tcu

transparencia

"我应该使用哪些工具来调查市政招标中的可疑合同？"

BM25搜索会从213个工具中筛选出相关工具（如

tce_sp

、

pncp

、

tcu

、

transparencia

）。

Pattern 4: Direct tool calls in code

模式4：在代码中直接调用工具

python

import asyncio
from mcp_brasil.data.bacen.tools import buscar_serie_temporal
from mcp_brasil.data.ibge.tools import buscar_municipios

async def main():
    # Selic rate last 12 months
    selic = await buscar_serie_temporal(codigo="432", ultimos=12)
    
    # All municipalities in São Paulo state
    municipios = await buscar_municipios(uf="SP")
    
    print(f"Selic entries: {len(selic)}")
    print(f"SP municipalities: {len(municipios)}")

asyncio.run(main())

python

import asyncio
from mcp_brasil.data.bacen.tools import buscar_serie_temporal
from mcp_brasil.data.ibge.tools import buscar_municipios

async def main():
    # 过去12个月的Selic利率
    selic = await buscar_serie_temporal(codigo="432", ultimos=12)
    
    # 圣保罗州的所有城市
    municipios = await buscar_municipios(uf="SP")
    
    print(f"Selic记录数: {len(selic)}")
    print(f"圣保罗州城市数量: {len(municipios)}")

asyncio.run(main())

Pattern 5: Using brasilapi for CNPJ/CEP lookup

模式5：使用brasilapi查询CNPJ/CEP

python

from mcp_brasil.data.brasilapi.tools import consultar_cnpj, consultar_cep

async def lookup():
    empresa = await consultar_cnpj(cnpj="00000000000191")  # Banco do Brasil
    endereco = await consultar_cep(cep="01310100")         # Av. Paulista

python

from mcp_brasil.data.brasilapi.tools import consultar_cnpj, consultar_cep

async def lookup():
    empresa = await consultar_cnpj(cnpj="00000000000191")  # 巴西银行
    endereco = await consultar_cep(cep="01310100")         # 保利斯塔大道

Natural Language Query Examples

自然语言查询示例

Once the server is connected to your AI client:

undefined

将服务器连接到AI客户端后，即可进行以下查询：

undefined

Economic analysis

经济分析

"Qual a tendência da taxa Selic nos últimos 12 meses? Compare com IPCA."

"过去12个月的Selic利率趋势如何？与IPCA指数进行比较。"

Legislative research

立法研究

"Quais projetos de lei sobre IA tramitaram na Câmara em 2024? Quem foram os autores?"

"2024年众议院有哪些关于AI的法案？提案人是谁？"

Transparency / anti-corruption

透明度/反腐败

"Quais os 10 maiores contratos do governo federal em 2024?"

"2024年联邦政府的十大合同是哪些？"

Cross-state comparison

跨州比较

"Compare gastos per capita com saúde em SP e MG cruzando TCE-SP e IBGE."

"结合TCE-SP和IBGE数据，比较圣保罗州和米纳斯吉拉斯州的人均医疗支出。"

Judiciary

司法

"Busque processos sobre licitação irregular no TCU. Quais as penalidades?"

"查询联邦审计法院中关于违规招标的案件，处罚措施有哪些？"

Electoral finance

选举资金

"Quais os maiores doadores da campanha do candidato X?"

"候选人X的主要竞选捐赠者是谁？"

Environment

环境

"Quantos focos de queimada foram registrados no Cerrado em agosto 2024?"

"2024年8月塞拉多地区记录了多少起野火？"

Document generation (redator feature)

文档生成（redator功能）

"Redija um ofício solicitando informações sobre o contrato 001/2024 com dados reais do Portal da Transparência."

---

"使用透明度门户的真实数据，起草一份关于001/2024号合同的信息查询公函。"

---

Troubleshooting

故障排除

Server not starting

服务器无法启动

bash

undefined

bash

undefined

Verify installation

验证安装

python -m mcp_brasil.server --help

Check uvx finds the package

检查uvx能否找到该包

uvx --from mcp-brasil python -c "import mcp_brasil; print(mcp_brasil.version)"

undefined

uvx --from mcp-brasil python -c "import mcp_brasil; print(mcp_brasil.version)"

undefined

API returning 401/403

API返回401/403错误

```
transparencia
```
and
```
datajud
```
silently degrade without keys — set
```
TRANSPARENCIA_API_KEY
```
and
```
DATAJUD_API_KEY
```
for full access
Keys are free: Transparência | DataJud

```
transparencia
```
和
```
datajud
```
在无密钥时会自动降级使用——设置
```
TRANSPARENCIA_API_KEY
```
和
```
DATAJUD_API_KEY
```
即可获得完整访问权限
密钥可免费获取：Transparência | DataJud

Too many tools visible (context overflow)

显示的工具过多（上下文溢出）

Set

MCP_BRASIL_TOOL_SEARCH=bm25

(default) — only tools relevant to the current query are surfaced. Use

code_mode

to expose all tools, or

none

to disable filtering.

设置

MCP_BRASIL_TOOL_SEARCH=bm25

（默认值）——仅显示与当前查询相关的工具。使用

code_mode

可显示所有工具，或使用

none

禁用过滤。

Timeout errors on slow government APIs

政府API响应缓慢导致超时错误

bash

MCP_BRASIL_HTTP_TIMEOUT=60.0    # increase timeout
MCP_BRASIL_HTTP_MAX_RETRIES=5   # increase retries

bash

MCP_BRASIL_HTTP_TIMEOUT=60.0    # 增加超时时间
MCP_BRASIL_HTTP_MAX_RETRIES=5   # 增加重试次数

Feature not auto-discovered

功能未被自动发现

Ensure your feature folder exports both:

```
FEATURE_META
```
in
```
__init__.py
```
```
mcp: FastMCP
```
instance in
```
server.py
```

Run

make inspect

to verify your feature appears in the tool list.

确保功能文件夹同时导出：

```
__init__.py
```
中的
```
FEATURE_META
```
```
server.py
```
中的
```
mcp: FastMCP
```
实例

运行

make inspect

验证功能是否出现在工具列表中。

Running tests for a specific feature

为特定功能运行测试

bash

make test-feature F=bacen
make test-feature F=transparencia

bash

make test-feature F=bacen
make test-feature F=transparencia

Key Design Principles

核心设计原则

Async everywhere —
```
httpx
```
async client, all tools are
```
async def
```
Pydantic v2 — all API responses validated through typed schemas
Rate limiting with backoff — built into
```
_shared/http.py
```
, transparent to feature code
Zero manual registration — add a folder → it's discovered automatically
BM25 smart filtering — prevents context window bloat from 213 tools
Graceful degradation — APIs requiring keys still work (with reduced limits) without them

全异步——基于
```
httpx
```
异步客户端，所有工具均为
```
async def
```
定义
Pydantic v2——所有API响应均通过类型化模型验证
带退避的速率限制——内置在
```
_shared/http.py
```
中，对功能代码透明
零手动注册——添加文件夹即可自动被发现
BM25智能过滤——避免213个工具导致的上下文窗口膨胀
优雅降级——需要密钥的API在无密钥时仍可使用（功能受限）

mcp-brasil-public-apis

Original

Translation

mcp-brasil: MCP Server for 28 Brazilian Public APIs

mcp-brasil：面向28个巴西公共API的MCP Server

Installation

安装

pip

pip方式

uv (recommended)

uv方式（推荐）

Quick Setup by Client

按客户端快速配置

Claude Desktop

Claude Desktop

VS Code / Cursor

VS Code / Cursor

Claude Code CLI

Claude Code CLI

HTTP Transport (other clients)

HTTP传输（其他客户端）

Server at http://localhost:8000/mcp

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

Environment Variables

环境变量

Optional — 26 other APIs work without any keys

可选——其余26个API无需密钥即可使用

Tuning

调优参数

API Coverage (28 Features, 213 Tools)

API覆盖范围（28类功能，213个工具）

Meta-Tools (Root Server)

元工具（根服务器）

Development Commands

开发命令

Architecture: Package by Feature + Auto-Registry

架构：按功能打包+自动注册

Adding a New Feature

添加新功能

__init__.py — Required export

__init__.py——必须导出

server.py — Required export

server.py——必须导出

client.py — Async HTTP pattern

client.py——异步HTTP模式

schemas.py — Pydantic v2 models

schemas.py——Pydantic v2模型

tools.py — Tool registration

tools.py——工具注册

tests/data/myfeature/test_tools.py — Test pattern

tests/data/myfeature/test_tools.py——测试模式

Common Usage Patterns

常见使用模式

Pattern 1: Cross-reference with planejar_consulta

模式1：使用planejar_consulta进行跨API关联

Pattern 2: Parallel execution with executar_lote

模式2：使用executar_lote进行并行执行

Pattern 3: Smart discovery with recomendar_tools

模式3：使用recomendar_tools进行智能发现

Pattern 4: Direct tool calls in code

模式4：在代码中直接调用工具

Pattern 5: Using brasilapi for CNPJ/CEP lookup

模式5：使用brasilapi查询CNPJ/CEP

Natural Language Query Examples

自然语言查询示例

Economic analysis

经济分析

Legislative research

立法研究

Transparency / anti-corruption

透明度/反腐败

Cross-state comparison

跨州比较

Judiciary

司法

Electoral finance

选举资金

Environment

环境

Document generation (redator feature)

`init.py`
— Required export

`init.py`
——必须导出

`server.py`
— Required export

`server.py`
——必须导出

`client.py`
— Async HTTP pattern

`client.py`
——异步HTTP模式

`schemas.py`
— Pydantic v2 models

`schemas.py`
——Pydantic v2模型

`tools.py`
— Tool registration

`tools.py`
——工具注册

`tests/data/myfeature/test_tools.py`
— Test pattern

`tests/data/myfeature/test_tools.py`
——测试模式

Pattern 1: Cross-reference with
`planejar_consulta`

模式1：使用
`planejar_consulta`
进行跨API关联

Pattern 2: Parallel execution with
`executar_lote`

模式2：使用
`executar_lote`
进行并行执行

Pattern 3: Smart discovery with
`recomendar_tools`

模式3：使用
`recomendar_tools`
进行智能发现