MCP Compras.gov.br

Compras.gov.br 생태계의 공개 API를 단일 패키지로 통합한 MCP 서버입니다. 계약 기획 및 계약 집행 분야의 분석가와 기술자를 대상으로 합니다.

다음 작성을 지원합니다:

• 예비 기술 연구 (ETP)

• 참조 약관 (TR)

• IN SEGES/ME 65/2021 표준에 따른 가격 조사

• 공급업체 제재 확인 (CEIS, CNEP, CEAF)

• 참여(카로나)를 위한 가격 등록 명세서 (ARP) 분석

• 국가 공공 조달 포털 (PNCP)을 통한 기관 간 벤치마킹

지원되는 API (v1)

⚠️ 운영 주의사항

• Dados Abertos 상위의 /modulo-uasg/* 계열 비활성화: 2026년 5월 직접 프로브를 통해 확인됨 — 공식 스웨거에 나열되어 있음에도 불구하고 1_consultarUasg, 2_consultarOrgao 및 CSV 변형이 HTTP 404 ("Resource not found")를 반환합니다. SEGES 서버 버그로 MCP로는 수정이 불가능합니다. 영향을 받는 5개 도구(compras_uasg_listar/_consultar/_buscar + compras_orgao_listar/_consultar)는 404를 감지하고 대안을 제시하는 교육용 페이로드를 반환합니다: CNPJ로 단위를 확인하려면 compras_pncp_orgao_unidades(cnpj) (안정적이며 10-30초 소요 가능) 또는 유효 계약이 있는 UG를 나열하려면 compras_contrato_comprasnet_por_uasg(uasg).

• /modulo-legado/*의 UASG 필터: 입찰 및 공고에 상위에서 확인된 Hibernate 버그가 있습니다 — 스웨거는 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}: 이 엔드포인트는 페이지 매김을 지원하지 않으며 단일 응답으로 전체 목록을 반환합니다 (1MB를 초과할 수 있음). 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

원격 (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

설정

Transparência 키 무료 등록: https://api.portaldatransparencia.gov.br/api-de-dados/cadastrar-email

모든 구성 가능한 변수(시간 초과, 캐시 TTL, 기본 URL)는 .env.example을 참조하십시오.

도구 (총 85개)

기능 도메인별 그룹화:

전체 목록은 manifest.json 또는 MCP Inspector의 tools/list를 통해 확인할 수 있습니다.

일반적인 흐름

인체공학적 의자 구매를 위한 ETP:

1. compras_catmat_buscar with termo="cadeira ergonomica" → codigo_item_catalogo 획득

2. compras_pesquisar_precos_para_etp (복합) with tipo="material" → 중앙값/평균/표준편차 + IQR 제외

3. compras_pgc_por_catalogo to see what other agencies plan to buy

4. compras_arp_listar with apenas_vigentes=True → 유효한 명세서, 참여 가능

낙찰 전 공급업체 분석:

1. compras_perfil_fornecedor_completo (복합) with CNPJ — 한 번 호출로 등록 + 제재 + 유효 계약 반환

갱신 대상 계약 목록:

1. compras_contratos_listar_por_fim_vigencia with data_fim_vigencia near

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에 의해 감지됩니다 — 존재하면 0.0.0.0:$PORT에서 HTTP, 없으면 stdio.

상태

v0.2.0 — 85개의 도구가 등록되었으며 Claude Desktop 및 Railway를 통한 종단 간 테스트 준비가 되었습니다.