io.github.Licinexus/mcp MCP Server

<p align="right"> 🇧🇷 Português · 🇺🇸 <a href="README.en.md"><b>English version</b></a> </p> <p align="center"> <a href="https://licinexus.com.br"> <img src=".github/assets/logo.png" alt="Licinexus" width="380"> </a> </p> <h1 align="center">@licinexusbr/mcp</h1> <p align="center"> Acesso conversacional aos dados de licitações públicas brasileiras — direto do Claude Desktop, Cursor, Continue ou qualquer cliente compatível com MCP. </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/licença-MIT-blue.svg" alt="MIT"></a> <a href="https://developercertificate.org/"><img src="https://img.shields.io/badge/DCO-obrigatório-green.svg" alt="DCO"></a> <a href="https://pncp.gov.br"><img src="https://img.shields.io/badge/dados-PNCP%20%2B%20Receita%20Federal-yellow.svg" alt="PNCP + Receita"></a> <a href="https://www.npmjs.com/package/@licinexusbr/mcp"><img src="https://img.shields.io/npm/v/@licinexusbr/mcp.svg?label=npm" alt="npm"></a> </p> <p align="center"> Mantido pela <a href="https://licinexus.com.br"><b>Licinexus</b></a> como contribuição open source ao ecossistema brasileiro de govtech. </p> <p align="center"> 🔔 <b>Quer notificações de novas versões?</b> Clica em <b>Watch → Custom → Releases</b> no topo do repositório — toda nova release cai na sua caixa de notificações sem encher o feed. </p> <!-- BEGIN: hero demo --> <p align="center"> <img src=".github/assets/demo.gif" alt="Demo: Licinexus MCP em ação contra PNCP + Receita Federal" width="900"> </p> <!-- END: hero demo -->

📺 A demonstração acima é um script CLI chamando os mesmos adaptadores que o LLM usa, contra PNCP e BrasilAPI ao vivo. A experiência no Claude Desktop / Cursor é idêntica — mesmas ferramentas, mesmos dados, com o LLM fazendo a interpretação em linguagem natural.

---

O que faz

Encapsula os endpoints mais úteis do Portal Nacional de Contratações Públicas (PNCP) e dos dados de CNPJ da Receita Federal, para que um LLM consiga responder perguntas reais sobre contratações públicas brasileiras:

• "Quais editais de TI no Sudeste publicados nos últimos 7 dias com valor acima de R$ 500 mil?"
• "Existe ata de registro de preço vigente com saldo para notebook no estado de SP?"
• "Qual o histórico de contratos do CNPJ X com órgãos públicos federais nos últimos 2 anos?"
• "O que a Prefeitura de Y planeja comprar este ano segundo o PCA?"
• "Resuma este edital e me dê uma lista de verificação de viabilidade."

🚀 Como usar

Pré-requisitos

• Node.js 18 ou superior instalado (nodejs.org)
• Qualquer cliente compatível com MCP (lista abaixo)

Nenhuma chave de API, nenhum cadastro, nenhum banco local — o servidor consulta endpoints públicos diretamente.

⚠️ Importante: Este é um servidor MCP stdio-based. Você não roda ele diretamente no terminal — é o cliente MCP (Claude Desktop, Cursor, etc.) que invoca o servidor quando precisa, e a comunicação acontece por JSON-RPC via stdin/stdout. Se você executar npx @licinexusbr/mcp direto no terminal, vai parecer que "travou" — é normal, o servidor está esperando o cliente conectar.

Da mesma forma, npx -y @licinexusbr/mcp não é uma instalação global — apenas baixa o pacote pra um cache local (~/.npm/_npx/) e executa. O cliente MCP invoca npx toda vez que precisa do servidor; execuções subsequentes usam o cache e são instantâneas. (Você também pode usar npm exec em vez de npx — são equivalentes.)

---

1. Claude Desktop ⭐ (recomendado)

Caminho A — Via UI (Claude Desktop ≥ 4.x)

1. Abra o Claude Desktop
2. Cmd + , (macOS) ou Ctrl + , (Windows) → Configurações
3. Barra lateral → Conectores
4. Clica em "Editar Configuração" (Aplicativo desktop → Desenvolvedor)
5. Abre o arquivo claude_desktop_config.json no seu editor

Substitua (ou adicione dentro de mcpServers):

{
  "mcpServers": {
    "licinexus": {
      "command": "npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  }
}

6. Salve o arquivo (Cmd+S)
7. Encerre o Claude completamente (Cmd+Q — não basta fechar a janela) e reabra

Caminho B — Editando o arquivo direto

SO	Caminho
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	Não oficialmente suportado pelo Claude Desktop ainda

Como verificar que funcionou

Após reabrir, na conversa nova:

• Em Configurações → Conectores → licinexus, você deve ver 18 ferramentas listadas (search_licitacoes, get_cnpj_data, etc.)
• No campo de prompt, digite:

Quais ferramentas do licinexus você tem disponíveis?

O Claude deve listar as 18 ferramentas. Pode prosseguir.

Primeiros prompts para testar

Me mostra os dados do CNPJ 00000000000191 (Banco do Brasil)

Tem ata de registro de preço vigente para notebook em São Paulo com saldo disponível?

O que a Prefeitura de Juiz de Fora planeja comprar este ano segundo o PCA?

Quais editais de tecnologia da informação foram publicados nos últimos 7 dias acima de R$ 200 mil?

---

2. Cursor

Cursor suporta MCP servers nativamente. Crie/edite o arquivo ~/.cursor/mcp.json:

{
  "mcpServers": {
    "licinexus": {
      "command": "npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  }
}

Ou via UI: Cursor → Settings → MCP → Add new MCP server.

Reinicie o Cursor. As ferramentas aparecem no chat do Composer.

---

3. Continue.dev (VS Code / JetBrains)

Edite o arquivo ~/.continue/config.json (ou config.yaml):

{
  "mcpServers": [
    {
      "name": "licinexus",
      "command": "npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  ]
}

Recarregue o Continue (Cmd+Shift+P → "Continue: Reload"). As ferramentas ficam disponíveis no chat.

---

4. Cline / Roo Code (extensão VS Code)

Pela UI do Cline:

1. Abra a extensão Cline na sidebar do VS Code
2. Ícone de configurações → MCP Servers → Edit MCP Settings
3. Adicione:

{
  "mcpServers": {
    "licinexus": {
      "command": "npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  }
}

---

5. Zed editor

Edite ~/.config/zed/settings.json (macOS/Linux) e adicione:

{
  "context_servers": {
    "licinexus": {
      "command": {
        "path": "npx",
        "args": ["-y", "@licinexusbr/mcp"]
      }
    }
  }
}

Reinicie o Zed.

---

6. ChatGPT

O ChatGPT consumer (web) não suporta MCP stdio nativamente até o momento. Mas dá pra usar via:

Via OpenAI Agents SDK (Python)

from openai import OpenAI
from openai.agents import Agent, MCPServerStdio

server = MCPServerStdio(
    command="npx",
    args=["-y", "@licinexusbr/mcp"]
)

agent = Agent(
    name="Licinexus Assistant",
    instructions="Você é um analista de licitações públicas brasileiras.",
    mcp_servers=[server]
)

ChatGPT Desktop

Versões recentes têm suporte limitado a MCP — verifique a documentação oficial da OpenAI para o estado atual.

---

7. Programaticamente (qualquer LLM via stdio)

Você pode chamar o servidor diretamente via stdio em qualquer linguagem que suporte o protocolo JSON-RPC do MCP. Exemplo Node:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@licinexusbr/mcp'],
});

const client = new Client({ name: 'meu-app', version: '1.0.0' }, { capabilities: {} });
await client.connect(transport);

const tools = await client.listTools();
console.log(tools);

const result = await client.callTool({
  name: 'search_atas_rp',
  arguments: { palavraChave: 'notebook', somenteVigentes: true },
});

---

🔧 Troubleshooting

"Server failed to start" ou "command not found: npx"

Causa: Claude Desktop / outro cliente não acha o npx no PATH.

Solução: use o caminho absoluto. Descubra com:

which npx

E substitua no config:

{
  "mcpServers": {
    "licinexus": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@licinexusbr/mcp"]
    }
  }
}

"Ferramentas não aparecem após salvar config"

Solução: reinicie o cliente completamente. No Mac, Cmd+Q (não basta fechar a janela). MCP servers só são carregados na inicialização.

"EACCES" ou erro de permissão

Causa: cache do npx corrompido ou permissão de escrita.

Solução:

npm cache clean --force
npx -y @licinexusbr/mcp

Versão antiga sendo executada

Causa: npx mantém cache. Para forçar a versão mais recente:

npx -y @licinexusbr/mcp@latest

E no config:

"args": ["-y", "@licinexusbr/mcp@latest"]

Timeout em consultas grandes

Algumas consultas (busca por palavra-chave ampla, datas longas) podem demorar — o PNCP às vezes leva 15-30s para responder. O servidor já implementa retry budget. Se persistir, refine a consulta com filtros mais específicos.

Logs e debug

Para inspecionar requisições/respostas, rode manualmente no terminal:

LICINEXUS_LOG_LEVEL=debug npx -y @licinexusbr/mcp

E em outra janela, observe os logs enquanto o cliente faz chamadas.

Idioma das mensagens de erro

Por padrão, as mensagens de erro retornadas pelas tools estão em português. Para recebê-las em inglês:

LICINEXUS_LANG=en npx -y @licinexusbr/mcp

Valores aceitos: pt (padrão) ou en.

Ferramentas (18)

Compras / Licitações

Ferramenta	O que faz
search_licitacoes	Busca editais por data, modalidade, UF, CNPJ do órgão, valor, palavra-chave
get_licitacao	Detalhes completos de um edital pelo número de controle PNCP
list_licitacao_itens	Itens (lotes) de um edital: descrições, quantidades, valores
list_licitacao_resultados	Resultados da disputa por item: vencedores, preços, fornecedores
list_licitacao_arquivos	Documentos do edital (PDFs, anexos, termos de referência)

Contratos

Ferramenta	O que faz
search_contratos	Busca contratos por data, órgão, fornecedor, valor
get_contrato	Detalhes completos de um contrato
list_contrato_termos	Termos aditivos (prorrogações, alterações de valor/prazo)
list_contrato_instrumentos	Instrumentos de cobrança (NFes, faturas)

Atas de Registro de Preço

Ferramenta	O que faz
search_atas_rp	Busca atas de RP — apenas vigentes por padrão. Encontra contratos utilizáveis.
get_ata_rp	Detalhes completos da ata + itens (com saldo disponível) + arquivos

Órgãos / Fornecedores / PCA

Ferramenta	O que faz
get_orgao	Perfil de órgão público (poder, esfera, natureza jurídica)
get_fornecedor_contratos	Contratos públicos de um CNPJ como fornecedor
search_pca	Plano de Contratação Anual — sinal antecipado do que será comprado
list_pca_itens	Itens planejados de um PCA específico

Enriquecimento de CNPJ

Ferramenta	O que faz
get_cnpj_data	Cadastro da Receita Federal (CNAEs, sócios, capital, situação) via BrasilAPI (padrão) ou MinhaReceita (CNPJ_PROVIDER=minhareceita)

Análise agregada (v0.2.0)

Ferramenta	O que faz
aggregate_licitacoes_por_periodo	Série temporal de contagem (e opcional valor) sobre janela de até 5 anos, com bucketing dia/semana/mês/ano. Filtros por modalidade, UF, município, CNPJ, esfera de governo
compare_periodos	Compara dois períodos lado-a-lado retornando totais + delta absoluto e percentual. Útil pra perguntas tipo "houve antecipação em ano eleitoral?"

Prompts prontos (4)

Fluxos pré-construídos que seu assistente pode invocar diretamente:

Prompt	O que faz
analyze_edital	Lista de verificação de viabilidade de um edital
analyze_orgao	Perfil 360° de um órgão público
find_arp_opportunities	Encontra atas vigentes com saldo disponível para uma palavra-chave
check_supplier	Verificação básica de dado público sobre um CNPJ fornecedor

Recursos (2)

URI	Conteúdo
licitacao://modalidades	Tabela de referência de modalidades PNCP (Lei 14.133)
licinexus://scope	O que este MCP faz e o que não faz

Exemplo de sessão

Você:   Tem alguma ata de registro de preço vigente para notebooks?
Claude: [chama search_atas_rp com palavraChave="notebook", somenteVigentes=true]
        Encontrei 12 atas vigentes mencionando notebooks. As 3 mais relevantes:
        1. Ministério da Justiça — vigência até 2026-12-31, valor estimado R$ 2,4M
        2. Prefeitura de São Paulo — vigência até 2026-09-30...

Você:   Detalhes da primeira, com saldos por item?
Claude: [chama get_ata_rp includeItens=true]
        - Item 1: Notebook tipo I (16GB RAM, 512GB SSD) — saldo 1.200 unid, R$ 4.800/un
        - Item 2: Notebook tipo II ...

Roteiro de evolução

• Fase 0 — Estrutura, governança, CI
• Fase 1 — Licitações (5 ferramentas)
• Fase 2 — Contratos + Aditivos + NFes (4 ferramentas)
• Fase 3 — Atas RP (2 ferramentas)
• Fase 4 — Órgãos + Fornecedores + PCA (4 ferramentas)
• Fase 5 — CNPJ + 4 prompts + 2 recursos (1 ferramenta)
• Teste de fumaça contra APIs reais (15/15 endpoints)
• Fase 6 — Lançamento público (11/05/2026 · v0.1.0 no npm)
• Fase 7 — Adapters comunitários (TCE/TCM estaduais, ComprasNet legado)

Escopo

O que este MCP faz

• Encapsula APIs públicas do governo brasileiro (PNCP, BrasilAPI).
• Devolve dado bruto estruturado — o LLM faz a análise.
• Mantém cache local de respostas pesadas (LRU em memória, TTL curto).

O que este MCP não faz

• Não consulta nenhuma infraestrutura nem banco de dados privado da Licinexus.
• Não inclui o motor de correspondência (matchmaking), pontuação de fornecedores, agregação de preços, artefatos gerados por IA ou qualquer dado proprietário da Licinexus.
• Não substitui o produto Licinexus — é uma ferramenta open source complementar para a camada pública dos mesmos dados.

Veja docs/architecture.md para o modelo completo de separação em três paredes.

Precisa de matchmaking automático, alertas ou gestão de propostas?

O produto Licinexus é construído sobre essas mesmas fontes públicas, com motor de correspondência proprietário, pontuação inteligente e artefatos gerados por IA. Este MCP intencionalmente não replica esses recursos.

→ https://licinexus.com.br

Como contribuir

PRs são bem-vindos sob o DCO (Developer Certificate of Origin) — assine seus commits com git commit --signoff.

Por favor, abra uma issue antes para discutir qualquer mudança não trivial. Veja CONTRIBUTING.md.

Suporte

Projeto comunitário. Melhor esforço, sem SLA. Issues são triadas em até 7 dias quando possível.

Para suporte pago e funcionalidades do produto, veja licinexus.com.br.

Segurança

Encontrou uma vulnerabilidade? Veja SECURITY.md para divulgação responsável (não abra issues públicas).

Licença

MIT © Licinexus. Veja LICENSE.