MCP Compras.gov.br

MCP-Server, der die öffentlichen APIs des Ökosystems Compras.gov.br in einem einzigen Paket vereint, gerichtet an Analysten und Techniker der Bereiche Beschaffungsplanung und Vertragsdurchführung.

Unterstützt die Erstellung von:

• Vorläufige technische Studien (ETP)

• Leistungsbeschreibungen (TR)

• Preisrecherche nach Standard IN SEGES/ME 65/2021

• Überprüfung von Lieferantensanktionen (CEIS, CNEP, CEAF)

• Analyse von Preisregistrierungsprotokollen (ARP) für Beitritte (carona)

• Behördenübergreifendes Benchmarking über das Nationale Portal für öffentliche Aufträge (PNCP)

Abgedeckte APIs (v1)

⚠️ Betriebshinweis

• Familie /modulo-uasg/* im Upstream Dados Abertos tot: bestätigt durch direkten Probe im Mai 2026 — 1_consultarUasg, 2_consultarOrgao und CSV-Varianten geben HTTP 404 ("Resource not found") zurück, obwohl sie im offiziellen Swagger aufgeführt sind. Bug des SEGES-Servers, der durch MCP nicht behoben werden kann. Die 5 betroffenen Tools (compras_uasg_listar/_consultar/_buscar + compras_orgao_listar/_consultar) erkennen den 404 und geben eine informative Nutzlast mit Alternativen zurück: compras_pncp_orgao_unidades(cnpj) zur Auflösung von Einheiten per CNPJ (stabil, kann 10-30s dauern), oder compras_contrato_comprasnet_por_uasg(uasg) zur Auflistung von UGs mit laufenden Verträgen.

• UASG-Filter in /modulo-legado/*: Ausschreibungen und Vergabeverfahren haben einen bestätigten Hibernate-Bug im Upstream — der Swagger dokumentiert co_uasg/uasg, aber das Attribut existiert nicht im View-Modell. Die Parameter wurden aus den Tools compras_legado_pregoes_listar und compras_legado_licitacoes_listar entfernt; um nach UASG zu filtern, clientseitig im Rückgabewert filtern.

• Portal da Transparência (CGU): Der CGU-Server ist durch AWS WAF "Human Verification" geschützt, das API-Aufrufe selbst mit gültigem Schlüssel blockieren kann (HTTP 405 + HTML-Seite). Wenn dies auftritt, geben alle Tools compras_sancao_* + das zusammengesetzte compras_checar_sancoes_fornecedor * die Sanktionsverzweigungen in compras_perfil_fornecedor_completo einen Fehler zurück. Dies ist ein Upstream-Problem — es gibt keine Lösung auf MCP-Seite.

• Comprasnet /api/contrato/ug/{uasg}: Der Endpunkt unterstützt keine Paginierung und gibt die vollständige Liste in einer einzigen Antwort zurück (kann über 1 MB groß sein). Das Tool compras_contrato_comprasnet_por_uasg wendet clientseitiges Slicing mit Caching der vollständigen Nutzlast an, um eine Überflutung des LLM zu vermeiden.

• CATMAT Textsuche defekt: Der Filter descricao (und Varianten nome, termo, q) von /modulo-material/4_consultarItemMaterial gibt das gesamte CATMAT-Universum zurück (~340k Artikel). Verwenden Sie strukturelle Filter über compras_catmat_listar_grupos → _listar_classes → _buscar mit codigo_grupo/codigo_classe. Das Tool gibt _aviso_filtro aus, wenn es das gesamte Universum erkennt.

Related MCP server: narajangteo-pro

Installation

Desktop-Erweiterung (.mcpb) — empfohlen für Claude Desktop

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

Lokal (Entwicklung)

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

Konfiguration

Kostenlose Registrierung des Transparenz-Schlüssels: https://api.portaldatransparencia.gov.br/api-de-dados/cadastrar-email

Siehe .env.example für alle konfigurierbaren Variablen (Timeouts, Cache-TTLs, Basis-URLs).

Tools (insgesamt 85)

Gruppiert nach funktionalem Bereich:

Die vollständige Liste befindet sich in manifest.json oder über tools/list im MCP Inspector.

Typische Abläufe

ETP für die Beschaffung ergonomischer Stühle:

1. compras_catmat_buscar mit termo="cadeira ergonomica" → codigo_item_catalogo erhalten

2. compras_pesquisar_precos_para_etp (zusammengesetzt) mit tipo="material" → Median/Mittelwert/Abweichung + IQR-Ausschluss

3. compras_pgc_por_catalogo um zu sehen, was andere Behörden zu kaufen planen

4. compras_arp_listar mit apenas_vigentes=True → laufende Protokolle für möglichen Beitritt

Lieferantenanalyse vor der Zulassung:

1. compras_perfil_fornecedor_completo (zusammengesetzt) mit der CNPJ — ein Aufruf gibt Registrierung + Sanktionen + laufende Verträge zurück

Inventar der zu verlängernden Verträge:

1. compras_contratos_listar_por_fim_vigencia mit nahem data_fim_vigencia

2. Für jeden relevanten Vertrag: compras_contrato_historico_aditivos, compras_contrato_ocorrencias

Interne Standards

• Standard-Envelope der Tools listar_*: {resultado, _pagina_atual, _total_paginas, _total_registros, _proxima_pagina, _cache_hit, _latency_ms}.

• SSoT der Beschreibungen: Parameterbeschreibungen leben in src/compras_mcp/schemas.py; Tools lesen über _helpers.desc(Model, "campo"). Test in tests/test_server.py erkennt Drift.

• LGPD: CPFs maskiert als 123.***.***-45; Anpassung mit INCLUIR_CPF_COMPLETO=true. Betroffene Tools enthalten _aviso_lgpd in der Nutzlast.

• Cache: TTL+LRU im Speicher (Standard) oder Redis, wenn REDIS_URL gesetzt. Jeder Bereich hat sein Präfix (CATALOGO, PRECOS, ATAS, etc.) — einstellbar über CACHE_<PREFIX>_TTL und CACHE_<PREFIX>_MAX_SIZE.

• Daten: 3 Formate pro API (YYYY-MM-DD, yyyyMMdd, YYYY-MM-DD HH:mm:ss) transparent konvertiert durch format_date(value, flavor).

• Framework: FastMCP 2.x. Transport erkannt durch PORT — vorhanden → HTTP auf 0.0.0.0:$PORT, nicht vorhanden → stdio.

Status

v0.2.0 — 85 Tools registriert und bereit für End-to-End-Tests mit Claude Desktop und Railway.