📺 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
notebookno 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/mcpdireto no terminal, vai parecer que "travou" — é normal, o servidor está esperando o cliente conectar.Da mesma forma,
npx -y @licinexusbr/mcpnão é uma instalação global — apenas baixa o pacote pra um cache local (~/.npm/_npx/) e executa. O cliente MCP invocanpxtoda vez que precisa do servidor; execuções subsequentes usam o cache e são instantâneas. (Você também pode usarnpm execem vez denpx— são equivalentes.)
1. Claude Desktop ⭐ (recomendado)
Caminho A — Via UI (Claude Desktop ≥ 4.x)
- Abra o Claude Desktop
Cmd + ,(macOS) ouCtrl + ,(Windows) → Configurações- Barra lateral → Conectores
- Clica em "Editar Configuração" (Aplicativo desktop → Desenvolvedor)
- Abre o arquivo
claude_desktop_config.jsonno seu editor
Substitua (ou adicione dentro de mcpServers):
{
"mcpServers": {
"licinexus": {
"command": "npx",
"args": ["-y", "@licinexusbr/mcp"]
}
}
}
- Salve o arquivo (
Cmd+S) - 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:
- Abra a extensão Cline na sidebar do VS Code
- Ícone de configurações → MCP Servers → Edit MCP Settings
- 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.
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.