MCP_Compras

# MCP Compras.gov.br

[![M8ven Score](https://m8ven.ai/badge/mcp/opedrosoares-mcp-compras-1wrbus?v=bf512ced4090ecbb6958bbd911c20716)](https://m8ven.ai/mcp/opedrosoares-mcp-compras-1wrbus)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.x-informational)](https://github.com/jlowin/fastmcp)

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**.

**100 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

| API | URL base | Autenticação |
|-----|----------|--------------|
| Dados Abertos Compras | `dadosabertos.compras.gov.br` | pública |
| PNCP — Portal Nacional | `pncp.gov.br/api/consulta` | pública |
| Portal da Transparência (CGU) | `api.portaldatransparencia.gov.br` | chave gratuita |
| Comprasnet Contratos | `contratos.comprasnet.gov.br/api` | pública (rotas `/api/*`) |
| BrasilAPI / MinhaReceita | `brasilapi.com.br` | pública |

### ⚠️ 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](https://github.com/opedrosoares/MCP_Compras/releases/latest) 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:

```bash
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)

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

Veja [Conectar a um cliente MCP](#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)](#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 .`):

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

Sem instalar globalmente, rodando direto do clone via `uv`:

```json
{
  "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`

```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:

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

  Ou direto no `.mcp.json`:

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

## Configuração

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `TRANSPARENCIA_API_KEY` | Não | Habilita as tools de sanções (CEIS, CNEP, CEPIM, CEAF, leniência). Sem ela, as demais ~90 tools (Dados Abertos, PNCP, Comprasnet, BrasilAPI) continuam funcionando normalmente. |
| `REDIS_URL` | Não | Cache TTL compartilhado em Redis. Recomendado em produção/Railway com múltiplos pods. Sem ela, cache fica em memória local (TTL+LRU). |
| `INCLUIR_CPF_COMPLETO` | Não | `false` (padrão): CPFs de servidores são mascarados (`123.***.***-45`). `true` retorna completo — use com critério (LGPD). |
| `LOG_LEVEL` | Não | `DEBUG`, `INFO` (padrão), `WARNING` ou `ERROR`. |
| `COMPRASNET_BEARER_TOKEN` | Não | Reservado para v2 (rotas autenticadas do Comprasnet Contratos via login gov.br). Sem efeito na v1. |

> **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](.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](https://railway.com), clique em **Sign Up** e faça login com GitHub, GitLab ou e-mail.

### 2. Instalar o Railway CLI

```bash
# macOS (Homebrew)
brew install railway

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

# Verificar
railway --version
```

### 3. Autenticar no terminal

```bash
railway login
```

### 4. Clonar o repositório

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

### 5. Criar o projeto no Railway

```bash
railway init -n mcp-compras
```

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