MCP Compras.gov.br

Servidor MCP que reúne em um único pacote as APIs públicas do ecossistema Compras.gov.br, voltado a analistas e técnicos das áreas de planejamento de contratação e execução contratual.

94 tools + 6 prompts + 6 resources cobrindo Dados Abertos, PNCP, Portal da Transparência/CGU, Comprasnet Contratos e BrasilAPI/Receita.

Apoia a elaboração de:

• Estudos Técnicos Preliminares (ETP)

• Termos de Referência (TR)

• Pesquisa de preços no padrão IN SEGES/ME 65/2021

• Checagem de sanções de fornecedores (CEIS, CNEP, CEPIM, CEAF)

• Análise de atas de registro de preço (ARP) para adesão (carona)

• Benchmark inter-órgãos via Portal Nacional de Contratações Públicas (PNCP)

• Due diligence de fornecedor (cadastro + sanções + Receita Federal)

APIs cobertas

⚠️ Aviso operacional

Cada linha abaixo foi confirmada por probe direto ao upstream (não é suposição). Rode compras_healthcheck a qualquer momento para ver a situação atual de cada módulo — esta lista é o retrato mais recente conhecido, o healthcheck é o retrato ao vivo.

Resolvidos (deixados aqui para quem encontrar issues antigas ou forks desatualizados):

• ✅ Família /modulo-uasg/* (compras_uasg_*, compras_orgao_*) — chegou a devolver 404 para todo mundo e a documentação atribuía isso a bug de roteamento sem fix possível. Diagnóstico corrigido em 2026-08 (v0.3.13): faltava o parâmetro obrigatório statusUasg/statusOrgao — a API responde 404 (não 400) quando ele falta. Hoje devolve ~22 mil UASGs e ~12 mil órgãos normalmente.

• ✅ compras_pesquisar_preco_material — o contrato da rota /modulo-pesquisa-preco/1_consultarMaterial mudou de codigoItemCatalogo=<int> para o par tipo (codigoItemCatalogo|codigoPdm) + codigo (string), sem versionar. Corrigido em v0.3.13.

Em aberto (limitação real do upstream, não do MCP):

• CATMAT busca textual quebrada: o filtro descricao (e variantes nome, termo, q) de /modulo-material/4_consultarItemMaterial ignora o valor e devolve o universo CATMAT inteiro (~340k itens). Use compras_catmat_listar_grupos → _listar_classes → _buscar com codigo_grupo/codigo_classe. A tool emite _aviso_filtro quando detecta o problema.

• Filtro UASG em /modulo-legado/*: pregões e licitações têm bug Hibernate confirmado no upstream — o swagger documenta co_uasg/uasg, mas o atributo não existe no modelo da view (400 Bad Request). Os parâmetros foram removidos das tools compras_legado_pregoes_listar e compras_legado_licitacoes_listar; para filtrar por UASG, faça client-side no retorno.

• compras_pncp_orgao_unidades: a rota /v1/orgaos/{cnpj}/unidades não é documentada no contrato oficial do PNCP Consulta — devolve 404 para CNPJs que não publicam diretamente (ex.: CNPJ raiz de órgão cujas unidades publicam com CNPJ próprio). A tool devolve diagnóstico com alternativas em vez de estourar exception.

• compras_pncp_contratacao_itens: pode devolver 404 mesmo quando a contratação-pai responde 200 — inconsistência observada no upstream, não reproduzida de forma determinística.

• Portal da Transparência (CGU): o servidor é protegido por AWS WAF que bloqueia (405 + página HTML "Human Verification") clientes HTTP com User-Agent genérico, mesmo com chave válida. O cliente deste MCP já envia um User-Agent browser-like como mitigação; se a CGU mudar as regras do WAF, as tools compras_sancao_* podem voltar a falhar — não há fix definitivo do lado do MCP.

• Comprasnet /api/contrato/ug/{uasg}: o endpoint não pagina e devolve a lista completa em uma resposta única (pode passar de 1 MB). compras_contrato_comprasnet_por_uasg aplica fatiamento client-side com cache do payload completo para não inundar o contexto do LLM.

Instalação

Opção 1 — Desktop Extension (.mcpb), recomendado para Claude Desktop

Baixe o compras.mcpb mais recente em Releases e abra com duplo-clique — o Claude Desktop instala e pede as configurações (chave da Transparência, Redis, etc.) automaticamente.

Ou gere localmente a partir do código-fonte:

git clone https://github.com/opedrosoares/MCP_Compras.git
cd MCP_Compras
python3 build_mcpb.py     # gera dist/compras.mcpb
open dist/compras.mcpb    # macOS — no Windows/Linux, abra com duplo-clique no Claude Desktop

Opção 2 — Local via uv (desenvolvimento ou Claude Code)

git clone https://github.com/opedrosoares/MCP_Compras.git
cd MCP_Compras
uv sync
uv run compras-mcp

Veja Conectar a um cliente MCP para registrar esse comando no Claude Desktop ou Claude Code.

Opção 3 — Remoto (Railway), para uso via web/mobile ou compartilhado por uma equipe

Não exige instalação local nenhuma — qualquer cliente MCP aponta para uma URL HTTP. Veja o passo a passo completo em Deploy remoto (Railway).

Conectar a um cliente MCP

Claude Code — .mcp.json do projeto ou ~/.claude.json (global)

Servidor local via stdio (assume compras-mcp instalado no PATH — via uv tool install . ou pip install .):

{
  "mcpServers": {
    "compras": {
      "command": "compras-mcp",
      "env": {
        "TRANSPARENCIA_API_KEY": "sua-chave-aqui"
      }
    }
  }
}

Sem instalar globalmente, rodando direto do clone via uv:

{
  "mcpServers": {
    "compras": {
      "command": "uv",
      "args": ["run", "--directory", "/caminho/para/MCP_Compras", "compras-mcp"],
      "env": {
        "TRANSPARENCIA_API_KEY": "sua-chave-aqui"
      }
    }
  }
}

TRANSPARENCIA_API_KEY é opcional: sem ela, todas as tools funcionam exceto as de sanções (compras_sancao_*, compras_checar_sancoes_fornecedor, ramificações de sanção em compras_perfil_fornecedor_completo).

Claude Desktop (registro manual, sem o .mcpb)

Edite o claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "compras": {
      "command": "compras-mcp",
      "env": {
        "TRANSPARENCIA_API_KEY": "sua-chave-aqui"
      }
    }
  }
}

Servidor remoto (Railway) via HTTP

Depois do deploy (ver seção abaixo), o endpoint MCP fica em https://SEU-PROJETO.up.railway.app/mcp. Não há autenticação própria — é o mesmo servidor, só que em modo HTTP em vez de stdio.

• claude.ai / Claude Desktop: Settings → Connectors → Adicionar conector personalizado → cole a URL.

• Claude Code — via CLI:

  claude mcp add --transport http compras-remoto https://SEU-PROJETO.up.railway.app/mcp

  Ou direto no .mcp.json:

  {
    "mcpServers": {
      "compras-remoto": {
        "type": "http",
        "url": "https://SEU-PROJETO.up.railway.app/mcp"
      }
    }
  }

Configuração

Dica: como obter a chave do Portal da Transparência

Cadastro gratuito, em minutos, em https://api.portaldatransparencia.gov.br/api-de-dados/cadastrar-email. A chave chega por e-mail e vai direto na variável TRANSPARENCIA_API_KEY.

Veja .env.example para todas as variáveis configuráveis, incluindo TTLs de cache por domínio, timeouts HTTP e base URLs (só para testes/mocks — os padrões já apontam para produção).

Deploy remoto (Railway)

O servidor detecta a env var PORT (injetada pelo Railway) e sobe automaticamente em modo HTTP; sem ela, sobe em stdio. Não há login por usuário — todas as APIs upstream são anônimas ou usam a chave da Transparência configurada no próprio servidor.

1. Criar conta no Railway

Acesse railway.com, clique em Sign Up e faça login com GitHub, GitLab ou e-mail.

2. Instalar o Railway CLI

# macOS (Homebrew)
brew install railway

# npm (qualquer plataforma)
npm install -g @railway/cli

# Verificar
railway --version

3. Autenticar no terminal

railway login

4. Clonar o repositório

git clone https://github.com/opedrosoares/MCP_Compras.git
cd MCP_Compras

5. Criar o projeto no Railway

railway init -n mcp-compras

Se tiver mais de um workspace, adicione --workspace "Nome do Workspace".

6. Adicionar Redis (recomendado)

railway add --database redis

O Redis vira cache compartilhado entre instâncias — sem ele, cada pod mantém seu próprio cache em memória.

7. Configurar variáveis de ambiente

railway variable set TRANSPARENCIA_API_KEY=sua-chave-aqui

REDIS_URL normalmente já é injetada automaticamente pelo plugin Redis do Railway (referência de outra variável do próprio projeto) — confira em railway variables se precisa setar manualmente.

8. Fazer o deploy

railway up

Aguarde o build (Dockerfile já incluso no repo, 2-3 minutos na primeira vez).

9. Gerar domínio público

railway domain

Gera uma URL como https://mcp-compras-production.up.railway.app.

10. Verificar o deploy

O endpoint MCP exige os headers do protocolo Streamable HTTP — uma requisição "crua" deve responder 406 (não erro de conexão), confirmando que o servidor está de pé:

curl -s -o /dev/null -w "%{http_code}\n" -X POST https://SEU-PROJETO.up.railway.app/mcp
# 406

Para uma checagem mais completa (versão, fontes upstream, chave da Transparência configurada), use a tool compras_versao ou compras_healthcheck a partir de um cliente MCP já conectado.

11. Conectar no Claude

Veja Servidor remoto (Railway) via HTTP acima.

Domínio customizado (opcional)

railway domain mcp.seu-orgao.gov.br

O comando devolve os registros DNS a configurar. Crie um CNAME no DNS do seu órgão apontando para o valor indicado; o certificado SSL é provisionado automaticamente. Para checar se a propagação/certificado já está ok:

railway domain status mcp.seu-orgao.gov.br

Atualizar o servidor

git pull
railway up

Requisitos de sistema

• Python ≥ 3.11

• uv (recomendado) ou pip

• Claude Code, Claude Desktop, ou qualquer cliente MCP compatível com stdio ou Streamable HTTP

• Redis (opcional, só para cache compartilhado em deploy com múltiplas instâncias)

• Chave gratuita do Portal da Transparência (opcional, só para tools de sanções)

Nenhuma dependência de sistema além do Python — diferente de MCPs que fazem OCR/scraping, este servidor só consome APIs REST públicas.

Tools (94 no total)

Agrupadas por domínio funcional:

A lista completa (nome + descrição de cada tool) está em manifest.json ou via tools/list no MCP Inspector.

Fluxos típicos

ETP de aquisição de cadeiras ergonômicas:

1. compras_catmat_buscar com termo="cadeira ergonomica" → obter codigo_item_catalogo

2. compras_pesquisar_precos_para_etp (composta) com tipo="material" → mediana/média/desvio + descarte IQR

3. compras_pgc_por_catalogo para ver o que outros órgãos planejaram comprar

4. compras_arp_listar com apenas_vigentes=True → atas vigentes para possível adesão

Análise de fornecedor antes de homologação:

1. compras_perfil_fornecedor_completo (composta) com o CNPJ — uma chamada devolve cadastro + sanções + contratos vigentes + dados da Receita

Inventário de contratos a renovar:

1. compras_contratos_listar_por_fim_vigencia com data_fim_vigencia próxima

2. Para cada contrato relevante: compras_contrato_historico_aditivos, compras_contrato_ocorrencias

Antes de uma demonstração ou de instruir processo:

1. compras_healthcheck(profundidade="rotas") — probe real contra o upstream em ~30s, retorna pronto_para_uso e qual módulo está degradado/fora, se algum.

Prompts MCP (6)

Diferente de tools (que o LLM invoca sozinho), prompts são selecionados pelo usuário no cliente MCP e expandem em um roteiro guiado usando as tools disponíveis. Úteis como ponto de partida para fluxos recorrentes.

Clientes que só consomem o primitivo tools (ex.: Claude.ai web) podem acessá-los via compras_listar_prompts / compras_obter_prompt.

Resources MCP (6)

Dados de referência que o cliente lista e lê sob demanda, sem gastar uma chamada de rede:

Clientes que só consomem o primitivo tools podem acessá-los via compras_listar_resources / compras_obter_resource.

Padrões internos

• Envelope padrão das tools listar_*: {resultado, _pagina_atual, _total_paginas, _total_registros, _proxima_pagina, _cache_hit, _latency_ms}.

• SSoT de descriptions: descrições de parâmetros vivem em src/compras_mcp/schemas.py; tools leem via _helpers.desc(Model, "campo"). Teste em tests/test_server.py detecta drift.

• LGPD: CPFs mascarados como 123.***.***-45; ajuste com INCLUIR_CPF_COMPLETO=true. Tools afetadas incluem _aviso_lgpd no payload.

• Cache: TTL+LRU em memória (default) ou Redis quando REDIS_URL setada. Cada domínio tem seu prefixo (CATALOGO, PRECOS, ATAS, ORGAOS, SANCOES, COMPOSTAS etc.) — ajustáveis via CACHE_<PREFIX>_TTL e CACHE_<PREFIX>_MAX_SIZE.

• Datas: 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 em 0.0.0.0:$PORT, ausente → stdio.

Links

• Changelog — cada release documenta a causa raiz encontrada, não só o sintoma

• Roadmap

• Issues upstream conhecidas — bugs reportáveis aos mantenedores da SEGES/CGU

• Repositório

• Dados Abertos Compras — Swagger

• PNCP Consulta — Swagger

• Portal da Transparência — Swagger

Licença

MIT — veja LICENSE.

Status

v0.3.15 — 94 tools + 6 prompts + 6 resources, em produção (Railway + Redis). Cada release recente foi validada em bateria de testes ponta a ponta contra o ambiente de produção, não apenas local — ver Changelog.