MCP Compras.gov.br

MCP 服务器，将 Compras.gov.br 生态系统的公共 API 整合到一个包中，面向 采购规划 和 合同执行 领域的分析师和技术人员。

支持编制：

• 初步技术研究 (ETP)

• 参考条款 (TR)

• 按 IN SEGES/ME 65/2021 标准进行价格调研

• 供应商制裁检查 (CEIS, CNEP, CEAF)

• 价格登记协议 (ARP) 分析，用于加入 (carona)

• 通过国家公共采购门户 (PNCP) 进行跨机构基准比较

覆盖的 API (v1)

⚠️ 操作警告

• 上游 Dados Abertos 中 /modulo-uasg/* 系列已失效：通过 2026-05 的直接探测确认 — 1_consultarUasg、2_consultarOrgao 及 CSV 变体返回 HTTP 404（"Resource not found"），尽管在官方 swagger 中仍有列出。这是 SEGES 服务器的错误，MCP 无法修复。受影响的 5 个工具（compras_uasg_listar/_consultar/_buscar + compras_orgao_listar/_consultar）检测到 404 并返回包含替代方案的教育性负载：compras_pncp_orgao_unidades(cnpj) 用于通过 CNPJ 解析单位（稳定，可能需要 10-30 秒），或 compras_contrato_comprasnet_por_uasg(uasg) 用于列出有有效合同的 UG。

• /modulo-legado/* 中的 UASG 过滤器：招标和采购存在上游确认的 Hibernate 错误 — swagger 记录了 co_uasg/uasg，但该属性在视图模型中不存在。这些参数已从工具 compras_legado_pregoes_listar 和 compras_legado_licitacoes_listar 中移除；如需按 UASG 过滤，请在返回结果中进行客户端过滤。

• Portal da Transparência (CGU)：CGU 服务器受 AWS WAF "Human Verification" 保护，即使使用有效密钥也可能阻止 API 调用（HTTP 405 + HTML 页面）。发生这种情况时，所有 compras_sancao_* 工具 + 复合工具 compras_checar_sancoes_fornecedor * 以及 compras_perfil_fornecedor_completo 中的制裁分支将返回错误。这是上游问题 — MCP 端无法修复。

• Comprasnet /api/contrato/ug/{uasg}：该端点不支持分页，并在单个响应中返回完整列表（可能超过 1 MB）。工具 compras_contrato_comprasnet_por_uasg 应用客户端切片，并缓存完整负载以避免淹没 LLM。

• CATMAT 文本搜索损坏：/modulo-material/4_consultarItemMaterial 的 descricao 过滤器（以及变体 nome、termo、q）返回整个 CATMAT 宇宙（约 34 万项）。请通过 compras_catmat_listar_grupos → _listar_classes → _buscar 使用结构过滤器，并指定 codigo_grupo/codigo_classe。当检测到整个宇宙时，工具会发出 _aviso_filtro。

Related MCP server: narajangteo-pro

安装

桌面扩展 (.mcpb) — 推荐用于 Claude Desktop

python build_mcpb.py     # gera dist/compras.mcpb
open dist/compras.mcpb   # Claude Desktop instala

本地 (开发)

uv sync
uv run compras-mcp

远程 (通过 Docker 在 Railway 上)

railway login && railway link
railway add redis                                # cache compartilhado
railway variables --set "TRANSPARENCIA_API_KEY=..."
railway up
railway domain                                   # https://mcp-compras.up.railway.app/mcp

配置

免费注册透明度密钥：https://api.portaldatransparencia.gov.br/api-de-dados/cadastrar-email

查看 .env.example 了解所有可配置变量（超时、缓存 TTL、基础 URL）。

工具 (共 85 个)

按功能领域分组：

完整列表见 manifest.json 或通过 MCP Inspector 的 tools/list。

典型流程

采购人体工学椅的 ETP：

1. compras_catmat_buscar 使用 termo="cadeira ergonomica" → 获取 codigo_item_catalogo

2. compras_pesquisar_precos_para_etp (复合) 使用 tipo="material" → 中位数/平均值/标准差 + IQR 剔除

3. compras_pgc_por_catalogo 查看其他机构计划采购的内容

4. compras_arp_listar 使用 apenas_vigentes=True → 有效协议，用于可能的加入

在批准前分析供应商：

1. compras_perfil_fornecedor_completo (复合) 使用 CNPJ — 一次调用返回注册 + 制裁 + 有效合同

待续签合同清单：

1. compras_contratos_listar_por_fim_vigencia 使用接近的 data_fim_vigencia

2. 对于每个相关合同：compras_contrato_historico_aditivos、compras_contrato_ocorrencias

内部模式

• 标准信封 用于 listar_* 工具：{resultado, _pagina_atual, _total_paginas, _total_registros, _proxima_pagina, _cache_hit, _latency_ms}。

• 描述的唯一真实来源 (SSoT)：参数描述位于 src/compras_mcp/schemas.py；工具通过 _helpers.desc(Model, "campo") 读取。测试 tests/test_server.py 检测漂移。

• LGPD：CPF 被屏蔽为 123.***.***-45；通过 INCLUIR_CPF_COMPLETO=true 调整。受影响的工具在负载中包含 _aviso_lgpd。

• 缓存：内存中的 TTL+LRU（默认）或设置 REDIS_URL 时使用 Redis。每个领域有自己的前缀（CATALOGO、PRECOS、ATAS 等）— 可通过 CACHE_<PREFIX>_TTL 和 CACHE_<PREFIX>_MAX_SIZE 调整。

• 日期：每个 API 有 3 种格式（YYYY-MM-DD、yyyyMMdd、YYYY-MM-DD HH:mm:ss），通过 format_date(value, flavor) 透明转换。

• 框架：FastMCP 2.x。通过 PORT 检测传输方式 — 存在时 → HTTP 在 0.0.0.0:$PORT，不存在时 → stdio。

状态

v0.2.0 — 已注册 85 个工具，准备好在 Claude Desktop 和 Railway 上进行端到端测试。