MCP Compras.gov.br

MCP server that brings together in a single package the public APIs of the Compras.gov.br ecosystem, aimed at analysts and technicians in the areas of procurement planning and contract execution.

Supports the preparation of:

• Preliminary Technical Studies (ETP)

• Terms of Reference (TR)

• Price research in the IN SEGES/ME 65/2021 standard

• Checking supplier sanctions (CEIS, CNEP, CEAF)

• Analysis of price registration minutes (ARP) for adherence (piggybacking)

• Inter-agency benchmarking via the National Public Procurement Portal (PNCP)

Covered APIs (v1)

⚠️ Operational notice

• Family /modulo-uasg/* dead on Dados Abertos upstream: confirmed via direct probe in 2026-05 — 1_consultarUasg, 2_consultarOrgao and CSV variants return HTTP 404 ("Resource not found") despite being listed in the official swagger. SEGES server bug with no possible fix via MCP. The 5 affected tools (compras_uasg_listar/_consultar/_buscar + compras_orgao_listar/_consultar) detect the 404 and return an educational payload with alternatives: compras_pncp_orgao_unidades(cnpj) to resolve units by CNPJ (stable, may take 10-30s), or compras_contrato_comprasnet_por_uasg(uasg) to list UGs with active contracts.

• UASG filter in /modulo-legado/*: auctions and bids have a confirmed Hibernate bug upstream — the swagger documents co_uasg/uasg but the attribute does not exist in the view model. The parameters were removed from the tools compras_legado_pregoes_listar and compras_legado_licitacoes_listar; to filter by UASG, do it client-side on the return.

• Transparency Portal (CGU): the CGU server is protected by AWS WAF "Human Verification" that can block API calls even with a valid key (HTTP 405 + HTML page). When this occurs, all tools compras_sancao_* + the composite compras_checar_sancoes_fornecedor * the sanction branches in compras_perfil_fornecedor_completo will return an error. It is an upstream problem — there is no fix on the MCP side.

• Comprasnet /api/contrato/ug/{uasg}: the endpoint does not support pagination and returns the complete list in a single response (may exceed 1 MB). The tool compras_contrato_comprasnet_por_uasg applies client-side slicing with full payload cache to avoid flooding the LLM.

• CATMAT broken textual search: the descricao filter (and variants nome, termo, q) of /modulo-material/4_consultarItemMaterial returns the entire CATMAT universe (~340k items). Use structural filters via compras_catmat_listar_grupos → _listar_classes → _buscar with codigo_grupo/codigo_classe. The tool emits _aviso_filtro when it detects the entire universe.

Related MCP server: narajangteo-pro

Installation

Desktop Extension (.mcpb) — recommended for Claude Desktop

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

Local (development)

uv sync
uv run compras-mcp

Remote (Railway via 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

Configuration

Free registration of the Transparency key: https://api.portaldatransparencia.gov.br/api-de-dados/cadastrar-email

See .env.example for all configurable variables (timeouts, cache TTLs, base URLs).

Tools (85 total)

Grouped by functional domain:

The complete list is in manifest.json or via tools/list in the MCP Inspector.

Typical flows

ETP for acquiring ergonomic chairs:

1. compras_catmat_buscar with termo="cadeira ergonomica" → get codigo_item_catalogo

2. compras_pesquisar_precos_para_etp (composite) with tipo="material" → median/mean/stddev + IQR discard

3. compras_pgc_por_catalogo to see what other agencies planned to buy

4. compras_arp_listar with apenas_vigentes=True → active minutes for possible adherence

Supplier analysis before homologation:

1. compras_perfil_fornecedor_completo (composite) with the CNPJ — one call returns registration + sanctions + active contracts

Inventory of contracts to renew:

1. compras_contratos_listar_por_fim_vigencia with data_fim_vigencia near

2. For each relevant contract: compras_contrato_historico_aditivos, compras_contrato_ocorrencias

Internal patterns

• Standard envelope of the listar_* tools: {resultado, _pagina_atual, _total_paginas, _total_registros, _proxima_pagina, _cache_hit, _latency_ms}.

• SSoT of descriptions: parameter descriptions live in src/compras_mcp/schemas.py; tools read via _helpers.desc(Model, "campo"). Test in tests/test_server.py detects drift.

• LGPD: CPFs masked as 123.***.***-45; adjust with INCLUIR_CPF_COMPLETO=true. Affected tools include _aviso_lgpd in the payload.

• Cache: TTL+LRU in memory (default) or Redis when REDIS_URL is set. Each domain has its prefix (CATALOGO, PRECOS, ATAS, etc.) — adjustable via CACHE_<PREFIX>_TTL and CACHE_<PREFIX>_MAX_SIZE.

• Dates: 3 formats per API (YYYY-MM-DD, yyyyMMdd, YYYY-MM-DD HH:mm:ss) transparently converted by format_date(value, flavor).

• Framework: FastMCP 2.x. Transport detected by PORT — present → HTTP on 0.0.0.0:$PORT, absent → stdio.

Status

v0.2.0 — 85 tools registered and ready for end-to-end testing with Claude Desktop and Railway.