Brazilian Sanctions

巴西制裁 MCP 服务

一个 MCP（Model Context Protocol）服务，通过 Porta da Transparência API 提供对巴西制裁数据库的访问。

组件

• mcp_server.py - 提供巴西制裁搜索工具的 MCP 服务
• BrazillianSanctions.json - MCP 配置文件

功能

• 搜索 5 个巴西制裁登记库
• 从 API 响应中提取特定字段（名称、制裁机构、日期、地点）
• 根据结束日期检查制裁是否仍然有效
• 汇总所有登记库中的信息，提供全面概览
• 通过 AI 聊天机器人提供简单的自然语言界面（仅用于测试）
• 按 CNPJ、CPF 或公司名称搜索
• 提供详细的制裁信息，包括原因、日期和机构
• 使用 API 密钥进行安全身份验证
• 支持异步执行工具

支持的制裁登记库

登记库	用途	搜索方式
CNEP	国家处罚登记库	CNPJ、CPF
CEPIM	受制裁公职人员登记库	CNPJ、CPF
CEIS	不合格实体登记库	CNPJ、CPF
CEAF	公务员不合格登记库	CPF
宽大处理协议	宽大处理协议记录	名称、CNPJ

重要提示：只有宽大处理协议支持按名称搜索。由于 API 限制，其他登记库（CNEP、CEIS、CEPIM、CEAF）仅支持按 CNPJ/CPF 搜索。

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

或者

在 Claude/Cursor 中使用时，请执行

\BrazillianSanctions.json

示例查询：

• “我想知道 30.477.220/0001-71 是否受到巴西制裁；如果是，原因是什么？”
• “搜索宽大处理协议中的 Petrobras”
• “检查 CNPJ 为 11222333000181 的公司是否受到任何制裁”

MCP 服务工具

MCP 服务提供以下工具：

搜索工具

• search_cnep - 按 CNPJ、CPF、机构或日期范围搜索 CNEP（国家处罚登记库）
• search_cepim - 按 CNPJ、CPF 或上级机构搜索 CEPIM（受制裁公职人员登记库）
• search_ceis - 按 CNPJ、CPF、机构或日期范围搜索 CEIS（不合格实体登记库）
• search_ceaf - 按 CPF、机构或日期范围搜索 CEAF（公务员不合格登记库）
• search_acordos_leniencia - 按名称、CNPJ、状态或日期范围搜索宽大处理协议
• search_all_registers - 搜索所有登记库中的指定 CNPJ 或 CPF

分析工具

• check_sanction_status - 根据结束日期检查实体在所有登记库中是否仍受到制裁
• get_sanctioning_authorities - 获取对该实体实施制裁的机构信息
• get_location_info - 获取受制裁实体的地点/州信息（UF、机构所在地）
• get_comprehensive_overview - 汇总所有登记库中的信息，提供全面概览，包括名称、机构、日期、地点和状态

实用工具

• get_sanction_details - 获取特定制裁登记库类型的详细信息
• check_entity_sanctions - 检查实体在所有登记库中的制裁情况
• batch_search - 一次操作搜索多个证件号码（CNPJ 或 CPF）
• generate_sanctions_report - 根据多项搜索结果生成格式化文本报告

架构

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

证件号码格式

系统会自动清理证件号码（巴西 CNPJ 或 CPF）。格式化和未格式化的证件号码均可使用：

# These are equivalent:
"12.345.678/0001-00"
"123456780001000"
"123.456.789-66"
"12345678966"

错误处理

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

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

故障排除

问题	解决方案
未找到 API 密钥	在 .env 文件中设置 PORTAL_TRANSPARENCIA_API_KEY
连接超时	检查网络连接和 API 状态
未找到记录	验证 CNPJ/CPF 格式，并检查实体是否存在

参考资料

• API 文档：https://api.portaldatransparencia.gov.br/swagger-ui/index.html
• 透明门户：https://www.portaldatransparencia.gov.br/
• MCP 协议：https://modelcontextprotocol.io/
• Ollama：https://ollama.ai/

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