gov.br APIs MCP

govbr-apis-mcp

将巴西政府 API 转化为可供 Claude 调用的工具的 MCP 服务，它通过由目录驱动的网关实现：不为每个端点单独创建工具（端点有数百个，会占满客户端上下文），而是通过 5 个通用工具操作包含 116 个 API 的本地 YAML 目录。

只有声明了 openapi_url 的条目才有可加载的规范：目前有 Câmara dos Deputados 和 Portal da Transparência，共 116 个条目中的 2 个。对于这些条目，describe_api 会按需加载 OpenAPI 规范。其他所有可调用条目（参见下方的“目前可调用？”列）仅通过 call_api 访问，使用其描述和 docs_url 中列出的端点。

目录层级

层级	文件	访问模式	目前可调用？
public	src/govbr_apis_mcp/catalog_data/public.yaml	免费 — 无需身份验证或免费 API 密钥（IBGE、Banco Central、Câmara、Senado、Portal da Transparência、DataJud、Ipeadata、dados.gov.br…）	是
serpro	src/govbr_apis_mcp/catalog_data/serpro.yaml	Serpro 商业服务（loja.serpro.gov.br）— 每个签约 API 使用 OAuth2 客户端凭据，按调用付费	签订 Serpro 合同后：设置 SERPRO_* 变量
meia-entrada	src/govbr_apis_mcp/catalog_data/meia_entrada.yaml	半价票资格来源（学生 CIE、ID Jovem、PcD、e-MEC）— 请参阅 docs/meia-entrada.md 和 POC	CIE 可用（DNE 和 FESN）；其余需手动处理
conecta	src/govbr_apis_mcp/catalog_data/conecta.yaml	Conecta gov.br — 仅限公共部门实体使用；已将 95 个 API 编入索引，作为发现用的存根	暂不可用（待接入）

Conecta 层级的存在是为了让目录现在就能反映完整的生态版图，并在日后通过填入 base_url 和凭据来启用调用 — OAuth2 客户端凭据流程已经实现（Serpro 使用相同流程）。

工具

• search_catalog(query, category?) — 支持忽略重音符号的关键词搜索；报告匹配总数以及列表是否已截断。
• list_apis(category?, status?, limit?) — 列出条目，可调用的条目优先（依据目录中的状态，而非是否已设置你的凭据；请使用过滤条件：否则约 95 个 Conecta 存根会占据输出）。
• describe_api(api_id, path?, method?) — 目录元数据 + OpenAPI 操作列表；指定 path 时，提供参数／请求／响应架构（内联 $refs，并限制深度）。支持读取 JSON 或 YAML 格式的 OpenAPI 3 和 Swagger 2.0。
• call_api(api_id, path, method?, query?, body?, headers?) — 调用端点；根据目录条目解析基础 URL 和身份验证。
  • method 可以是 GET、HEAD、POST、PUT、PATCH、DELETE 或 OPTIONS；其他值会返回包含 allowed_methods 的错误。仅 POST、PUT 和 PATCH 接受 body。
  • path 相对于 base_url。. 和 .. 路径段（最多进行三轮百分号解码，将 \ 视为 / 并移除 ; 参数），以及任何超出 base_url 前缀的路径，都会被拒绝。包含 # 的路径也会被拒绝（片段永远不会发送；要表示字面量 #，请写作 %23），控制字符同样会被拒绝。
  • 嵌入 path 的查询字符串会与 query 合并；query 中的键会替换嵌入的同名键，列表值会重复对应的键。
  • 调用方的标头会进行不区分大小写的匹配，且 _ 等同于 -。Authorization、Proxy-Authorization、Host、Cookie 和 Accept-Encoding，以及连接、代理、转发和方法覆盖标头，会被丢弃并列入 ignored_headers（完整列表见 server.py）。受管理的凭据会最后应用，并始终具有优先权。标头名称或值无效时，不会被忽略，而是会导致调用失败并返回 error。
  • 在请求任何 OAuth2 令牌之前，会先验证方法、正文、标头和路径；无效输入会以 {"error": ...} 的形式返回。
  • 不会跟随 3xx 响应：响应会附带其 location（已脱敏，并根据请求的 URL 解析）。响应正文会截断至 60,000 个字符。
• credentials_status(api_id?) — 列出各 API 所需的环境变量及其设置状态，并提供 callable：表示 call_api 当前是否会接受该条目（available 和 unstable 条目可用；requires_contract 条目仅在其环境变量已设置时可用）。

POC：学生半价票

端到端功能流程（从 CIE 代码到资格判定），包括无需凭据的演示模式：poc/README.md。

安装

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest

在 Claude Code 中注册（.mcp.json 或 claude mcp add）：

{
  "mcpServers": {
    "govbr-apis": {
      "command": "/path/to/govbr-apis-mcp/.venv/bin/govbr-apis-mcp",
      "env": {
        "TRANSPARENCIA_API_KEY": "...",
        "DATAJUD_API_KEY": "..."
      }
    }
  }
}

通过 PyPI 安装：uvx govbr-apis-mcp（在上面的条目中设置 "command": "uvx" 和 "args": ["govbr-apis-mcp"]；无需检出代码）。每次发布都会自动发布到 PyPI 和 MCP Registry（publish.yml）。

也可以在容器中运行。该服务使用 stdio 通信，因此请保留 -i：

docker build -t govbr-apis-mcp . && docker run -i --rm -e TRANSPARENCIA_API_KEY=... govbr-apis-mcp

凭据

所有密钥均来自目录中按条目声明的环境变量（auth_config）。 仓库中不会存储任何内容。.env.example 列出了这些变量。可使用免费密钥的条目会提供 signup_url；Serpro 凭据随合同提供，可在 loja.serpro.gov.br 获取。 credentials_status 会报告凭据是否就绪。

服务不会读取 .env 文件，而且 MCP 客户端启动服务时使用的是精简环境，因此在 shell 中执行的 export 可能无法传递给它。请将变量放入客户端的 env 区块中（参见上方示例，或使用 claude mcp add -e KEY=value）。对于容器，请将 .env.example 复制到已被 git 忽略的文件（例如 .env.local），填写副本，并通过 docker run --env-file .env.local 传入。切勿在 .env.example 中填写真实值：该文件会纳入版本控制。

API 密钥（包括其值和任何前缀）会去除首尾空白，且必须为可打印 ASCII 字符；否则调用会失败，并返回 credential in <VAR> contains invalid characters，但不会回显密钥值。OAuth2 客户端 ID 和密钥只会去除首尾空白：它们会以 base64 编码传输，因此可以使用任意文本。端点返回的访问令牌也必须是可打印 ASCII 字符。令牌端点调用失败时，调用会返回 error 和 token_url，不包含响应正文或任何密钥。

身份验证配置：none、api_key（静态请求头，可选值前缀，例如 DataJud 的 APIKey <key>）、oauth2_client_credentials（令牌端点 + ID/密钥，使用内存令牌缓存；目前 Serpro 使用，Conecta 完成加入后也会使用）。

扩展目录

在 src/govbr_apis_mcp/catalog_data/ 中的 YAML 文件里添加条目。该目录属于软件包数据，因此 wheel、uvx 和 Docker 镜像都会包含目录内容。最低限度的字段为： id、name、provider、category、status、auth。如果 API 发布了规范，请添加 openapi_url——这样 describe_api 无需编写代码即可运行。使用 .venv/bin/python scripts/scrape_conecta.py 重新生成 Conecta 层级。如果页面未返回任何 API、返回的 ID 不符合目录要求，或条目数量少于当前条目的一半，该脚本会保留原文件（--force 只会覆盖最后一项检查）。

条目加载时会进行验证：ID 必须适合作为文件名；URL 必须使用 https，且主机必须在允许列表中（*.gov.br、*.leg.br、*.jus.br，以及几个指定主机）；主机名只能包含 [a-z0-9.-]（国际化名称请使用 punycode）。这是安全边界，而非风格要求——目录决定凭据会发送到哪里。只有在信任某主机能够接收凭据时，才使用 GOVBR_EXTRA_ALLOWED_HOSTS 添加该主机；同样的主机名规则也适用于它。

如需在不分叉仓库的情况下覆盖条目（例如加入 Conecta 后补充基本 URL），请将 GOVBR_EXTRA_CATALOG_DIR 指向一个包含 .yaml 或 .yml 文件的目录，其中相同 ID 的条目优先生效。目录不存在或不包含任何条目都会报错；目录内部存在重复 ID 也会报错；空值视为未设置。GOVBR_CATALOG_DIR 会完全替换基础目录，因此应将其视为可信输入。

开发

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/pytest

CI 会在 Python 3.12 上运行 ruff，并在 3.11–3.14 上运行测试套件，然后构建 wheel，并从全新安装中加载目录。

安全注意事项

• 响应不会写入磁盘。只有 OpenAPI 规范会缓存在 $XDG_CACHE_HOME/govbr-apis-mcp/（或 ~/.cache/govbr-apis-mcp/）中，有效期为 24 小时；文件名由 sha256(api_id + "\n" + openapi_url) 生成：绝不会使用 ID 本身，且 openapi_url 变更后不会继续提供旧规范。OAuth2 令牌仅保存在内存中。
• call_api 不跟随重定向——带凭据的请求不会因 3xx 被引导至其他主机；响应会返回（已脱敏的）location。它始终发送 Accept-Encoding: identity，因此服务端没有理由进行压缩。不过，60,000 个字符的截断限制针对的是解码后的文本：即使服务端仍然压缩，也可能在截断前将一个很小的数据块膨胀（这是已接受的风险；参见路线图）。
• API 设置的 Cookie 不会被存储或发回，因此一个 API 无法植入另一个 API 会收到的 Cookie。
• 规范获取仅以手动方式跟随重定向：最多 5 次跳转，并且每个 URL（首个 URL 和每个 Location）在发出请求前都必须使用 https 且位于允许列表中的主机上。响应正文上限为 5 MiB，接受 JSON 和 YAML（拒绝带有别名的 YAML，包括依赖别名的合并键），且文档必须包含 openapi 或 swagger。压缩响应会被拒绝，整个下载的时限为 60 秒；这两种情况都会返回 spec_error。
• httpx 和 httpcore 日志记录器保持在 WARNING 级别，因此 httpx 不会记录请求 URL（包括查询字符串）。
• 标记为 pii: true 的条目会将个人数据（CPF、姓名、照片）返回到客户端对话记录中。目前包括：meiaentrada-cie-validador、fesn-cie-validador（无需任何凭据即可调用：任何持有使用码的人都能获取持有者的数据）以及 Serpro 的三个条目。

路线图

• 作为公共部门实体申请加入 Conecta → 填写网关基础 URL 和凭据
• 为 Conecta 条目设置各 API 的 OpenAPI URL（链接自各详情页）
• 添加 Serpro 试用模式切换（使用已发布的演示令牌调用 -trial 基础 URL）
• 为付费 Serpro API 添加单次调用成本限制
• 对压缩的上游响应进行有界解压
• 向 SNJ 申请 conecta-id-jovem API（允许私人机构接入）
• 为不在 DNE 数据库中的 CIE 提供文档备用方案（DCE 和州级实体）

许可证

MIT - 参见 LICENSE。