MCP Compras.gov.br

Servidor MCP que reúne en un único paquete las APIs públicas del ecosistema Compras.gov.br, orientado a analistas y técnicos de las áreas de planificación de contratación y ejecución contractual.

Apoya la elaboración de:

• Estudios Técnicos Preliminares (ETP)

• Términos de Referencia (TR)

• Investigación de precios según el estándar IN SEGES/ME 65/2021

• Verificación de sanciones de proveedores (CEIS, CNEP, CEAF)

• Análisis de actas de registro de precios (ARP) para adhesión (carona)

• Benchmark inter-órganos vía Portal Nacional de Contrataciones Públicas (PNCP)

APIs cubiertas (v1)

⚠️ Aviso operacional

• Familia /modulo-uasg/* muerta en upstream Datos Abiertos: confirmado mediante sonda directa en 2026-05 — 1_consultarUasg, 2_consultarOrgao y variantes CSV retornan HTTP 404 ("Resource not found") a pesar de estar listadas en el swagger oficial. Error del servidor SEGES sin posible solución por el MCP. Las 5 tools afectadas (compras_uasg_listar/_consultar/_buscar + compras_orgao_listar/_consultar) detectan el 404 y retornan payload educativo con alternativas: compras_pncp_orgao_unidades(cnpj) para resolver unidades por CNPJ (estable, puede tardar 10-30s), o compras_contrato_comprasnet_por_uasg(uasg) para listar UGs con contratos vigentes.

• Filtro UASG en /modulo-legado/*: pregones y licitaciones tienen error Hibernate confirmado en el upstream — el swagger documenta co_uasg/uasg pero el atributo no existe en el modelo de la vista. Los parámetros fueron eliminados de las tools compras_legado_pregoes_listar y compras_legado_licitacoes_listar; para filtrar por UASG, haga client-side en el retorno.

• Portal de Transparencia (CGU): el servidor de la CGU está protegido por AWS WAF "Human Verification" que puede bloquear llamadas API incluso con clave válida (HTTP 405 + página HTML). Cuando esto ocurre, todas las tools compras_sancao_* + la compuesta compras_checar_sancoes_fornecedor

  • las ramificaciones de sanción en compras_perfil_fornecedor_completo retornarán error. Es un problema upstream — no hay solución por parte del MCP.

• Comprasnet /api/contrato/ug/{uasg}: el endpoint no soporta paginación y devuelve la lista completa en una única respuesta (puede superar 1 MB). La tool compras_contrato_comprasnet_por_uasg aplica segmentación client-side con caché del payload completo para evitar inundar el LLM.

• Búsqueda textual CATMAT rota: el filtro descricao (y variantes nome, termo, q) de /modulo-material/4_consultarItemMaterial retorna el universo CATMAT completo (~340k ítems). Use filtros estructurales vía compras_catmat_listar_grupos → _listar_classes → _buscar con codigo_grupo/codigo_clase. La tool emite _aviso_filtro cuando detecta el universo completo.

Related MCP server: narajangteo-pro

Instalación

Desktop Extension (.mcpb) — recomendado para Claude Desktop

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

Local (desarrollo)

uv sync
uv run compras-mcp

Remoto (Railway vía Docker)

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

Configuración

Registro gratuito de la clave de Transparencia: https://api.portaldatransparencia.gov.br/api-de-dados/cadastrar-email

Vea .env.example para todas las variables configurables (timeouts, TTLs de caché, URLs base).

Tools (85 en total)

Agrupadas por dominio funcional:

La lista completa está en manifest.json o vía tools/list en el MCP Inspector.

Flujos típicos

ETP de adquisición de sillas ergonómicas:

1. compras_catmat_buscar con termo="cadeira ergonomica" → obtener codigo_item_catalogo

2. compras_pesquisar_precos_para_etp (compuesta) con tipo="material" → mediana/media/desviación + descarte IQR

3. compras_pgc_por_catalogo para ver qué otros órganos planearon comprar

4. compras_arp_listar con apenas_vigentes=True → actas vigentes para posible adhesión

Análisis de proveedor antes de homologación:

1. compras_perfil_fornecedor_completo (compuesta) con el CNPJ — una llamada devuelve registro + sanciones + contratos vigentes

Inventario de contratos a renovar:

1. compras_contratos_listar_por_fim_vigencia con data_fim_vigencia próxima

2. Para cada contrato relevante: compras_contrato_historico_aditivos, compras_contrato_ocorrencias

Estándares internos

• Envoltorio estándar de las tools listar_*: {resultado, _pagina_atual, _total_paginas, _total_registros, _proxima_pagina, _cache_hit, _latency_ms}.

• SSoT de descripciones: las descripciones de parámetros viven en src/compras_mcp/schemas.py; las tools leen vía _helpers.desc(Model, "campo"). Prueba en tests/test_server.py detecta drift.

• LGPD: CPFs enmascarados como 123.***.***-45; ajuste con INCLUIR_CPF_COMPLETO=true. Tools afectadas incluyen _aviso_lgpd en el payload.

• Caché: TTL+LRU en memoria (predeterminado) o Redis cuando REDIS_URL está configurada. Cada dominio tiene su prefijo (CATALOGO, PRECOS, ATAS, etc.) — ajustables vía CACHE_<PREFIX>_TTL y CACHE_<PREFIX>_MAX_SIZE.

• Fechas: 3 formatos por API (YYYY-MM-DD, yyyyMMdd, YYYY-MM-DD HH:mm:ss) convertidos transparentemente por format_date(value, flavor).

• Framework: FastMCP 2.x. Transporte detectado por PORT — presente → HTTP en 0.0.0.0:$PORT, ausente → stdio.

Estado

v0.2.0 — 85 tools registradas y listas para prueba de extremo a extremo con Claude Desktop y Railway.