Brazilian PEP (Politically Exposed Person)

巴西 PEP MCP 服务

一个 MCP（Model Context Protocol）服务，通过 Porta da Transparência API 提供巴西 PEP（政治公众人物）和联邦公务员数据的访问。

组件

• mcp_server.py - 提供巴西 PEP 和公务员搜索工具的 MCP 服务
• pyproject.toml - 项目依赖项和配置
• requirements.txt - Python 依赖项

功能

• 按 CPF、姓名、职务、机构或日期范围搜索 PEP（政治公众人物）
• 搜索联邦行政部门公务员（文职和军职）
• 查询公务员薪酬数据
• 按机构汇总搜索公务员
• 查询职能和信任职位
• 获取个人完整的 PEP 状态
• 从 API 响应中提取特定字段
• 安全的 API 密钥身份验证
• 支持异步执行工具

数据来源

来源	用途	搜索条件
PEPs	政治公众人物	CPF、姓名、职务、机构、日期范围
Servidores	联邦行政部门公务员	CPF、姓名、机构、类型、状态
Remuneração	公务员薪酬	CPF、ID、月份/年份
Por Órgão	按机构划分的公务员	机构代码、类型、链接类型
Funções e Cargos	职能和职位	分页

API 密钥配置

使用此系统必须提供 API 密钥。

获取 API 密钥：

1. 访问：https://www.portaldatransparencia.gov.br/（需要巴西 CPF）
2. 登录或创建账户
3. 前往“Minha Conta” → “API Keys”或“Desenvolvedor”
4. 生成新的 API 密钥
5. 复制密钥（格式：abcd1234efgh5678ijkl9012）

设置：

在项目根目录创建 .env 文件：

PORTAL_TRANSPARENCIA_API_KEY=your_key_here

安全提示：切勿将 API 密钥提交到版本控制系统！

用法

运行 MCP 服务

MCP 服务可以独立运行，也可以由 MCP 客户端使用：

python mcp_server.py

查询示例：

• “检查 CPF 123.456.789-00 是否为 PEP”
• “搜索经济部中名为 Silva 的公务员”
• “获取 CPF 为 987.654.321-00 的公务员在 2026 年 1 月的薪酬数据”
• “列出机构 25000 中的所有 PEP”
• “搜索职能和信任职位”

MCP 服务工具

MCP 服务提供以下工具：

PEP 搜索工具

• search_peps - 按 CPF、姓名、职务、机构或日期范围搜索 PEP
• get_pep_info - 根据 CPF 获取某人的完整 PEP 信息

公务员搜索工具

• search_servidores - 按 CPF、姓名、机构、类型或状态搜索联邦行政部门公务员
• get_servidor_by_id - 按 ID 获取特定公务员
• search_servidores_remuneracao - 按 CPF 或 ID 以及月份/年份搜索公务员薪酬
• search_servidores_por_orgao - 按机构汇总搜索公务员
• search_funcoes_e_cargos - 搜索职能和信任职位

架构

User Query (Natural Language)
    ↓
Tool Selection & Execution
    ↓
MCP Tools / Direct API Calls
    ↓
Brazilian PEP API
    ↓
Detailed PEP/Servant Information
    ↓
Natural Language Response

文档格式处理

系统会自动清理文档号码（巴西 CPF）。带格式和不带格式的文档均可使用：

# These are equivalent:
"123.456.789-00"
"12345678900"

错误处理

系统包含全面的错误处理机制：

• API 连接错误
• 无效的文档格式
• 缺少 API 密钥
• 速率限制
• 格式错误的响应

故障排除

问题	解决方案
未找到 API 密钥	在 .env 文件中设置 PORTAL_TRANSPARENCIA_API_KEY
连接超时	检查互联网连接和 API 状态
未找到记录	验证 CPF 格式并确认此人是否存在
401 未授权	确认 API 密钥正确且有效

参考资料

• API 文档：https://api.portaldatransparencia.gov.br/swagger-ui/index.html
• Porta da Transparência：https://www.portaldatransparencia.gov.br/
• MCP 协议：https://modelcontextprotocol.io/

最后更新：2026 年 6 月 API 基础 URL：https://api.portaldatransparencia.gov.br/api-de-dados