novacrm-mcp

Servidor MCP (Model Context Protocol) oficial do NovaCRM. Conecta IAs como Claude Desktop, Cursor, Claude Code, Gemini CLI, Zed e Cline aos dados e operações da sua loja — clientes, produtos, estoque, pedidos, cupons, webhooks e métricas — tudo através da API pública v1 do NovaCRM, autenticado pela chave de API da loja.

• Zero dependências: JSON-RPC 2.0 sobre STDIO implementado na mão (Node ≥ 18).

• 27 ferramentas cobrindo o dia a dia da loja + 2 prompts prontos.

• Escopos respeitados: a chave define o que a IA pode fazer (leitura e/ou escrita), e os limites do plano e o rate limit valem normalmente.

┌──────────────┐   JSON-RPC/STDIO   ┌──────────────┐   HTTPS Bearer   ┌─────────────────┐
│  IA (Claude, │ ─────────────────▶ │ novacrm-mcp  │ ───────────────▶ │  API v1 do      │
│  Cursor, …)  │ ◀───────────────── │  (npx)       │ ◀─────────────── │  NovaCRM        │
└──────────────┘                    └──────────────┘                  └─────────────────┘

Instalação e uso rápido

# direto, sem instalar nada
NOVACRM_API_KEY="ncrm_live.suachave" npx novacrm-mcp

# ou instalando globalmente
npm install -g novacrm-mcp
NOVACRM_API_KEY="ncrm_live.suachave" novacrm-mcp

Gere sua chave em Console da API → Chaves de API no painel do NovaCRM (produção ncrm_live.… ou sandbox ncrm_test.…). A chave só é exibida na criação.

A chave define o que a IA pode fazer pelos escopos (ex.: products:read, orders:write). Crie uma chave enxuta se a IA só vai ler, e uma com escopos de escrita apenas quando confiar no agente.

Related MCP server: Shopify MCP Manager

Configuração por cliente

Claude Desktop

Edite claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json no macOS, %APPDATA%\Claude\claude_desktop_config.json no Windows):

{
  "mcpServers": {
    "novacrm": {
      "command": "npx",
      "args": ["novacrm-mcp"],
      "env": {
        "NOVACRM_API_KEY": "ncrm_live.suachave.aqui"
      }
    }
  }
}

Reinicie o Claude Desktop — o martelinho 🔨 aparecerá com as ferramentas novacrm_* disponíveis.

Cursor

Crie .cursor/mcp.json no projeto (ou configure em Settings → MCP):

{
  "mcpServers": {
    "novacrm": {
      "command": "npx",
      "args": ["novacrm-mcp"],
      "env": {
        "NOVACRM_API_KEY": "ncrm_live.suachave.aqui"
      }
    }
  }
}

Claude Code

claude mcp add novacrm -e NOVACRM_API_KEY=ncrm_live.suachave.aqui -- npx novacrm-mcp

Gemini CLI

Adicione ao settings.json do Gemini CLI:

{
  "mcpServers": {
    "novacrm": {
      "command": "npx",
      "args": ["novacrm-mcp"],
      "env": { "NOVACRM_API_KEY": "ncrm_live.suachave.aqui" },
      "timeout": 15000
    }
  }
}

Zed, Cline e outros

Qualquer cliente MCP com transporte STDIO funciona: aponte o comando para npx novacrm-mcp com a variável NOVACRM_API_KEY.

Ferramentas disponíveis (27)

Status de pedido válidos: pending_payment, new, processing, completed, cancelled.

Prompts prontos

• resumo_diario_loja — briefing executivo da loja (faturamento, pedidos pendentes e alertas de estoque).

• auditoria_estoque — auditoria do catálogo com plano de reposição (aceita limite_alerta).

Variáveis de ambiente

Para apontar para o sandbox: NOVACRM_BASE_URL=https://sandbox.novacrm.com.br/api/v1 com uma chave ncrm_test.….

Segurança

• A chave trafega apenas no header Authorization da API (no STDIO fica na variável de ambiente do processo local, nunca sai da sua máquina).

• Toda chamada passa pelo rate limit por chave e pelos limites do plano (Free 100/mês, Pro 10.000/mês, Enterprise 100.000/mês).

• Escopos por ferramenta: uma chave sem orders:write nunca cancela um pedido, mesmo que a IA tente. Deletar definitivamente exige o escopo dangerous:delete.

• Zero dependências npm: nada para instalar ou vulnerabilizar.

Desenvolvimento

Sem etapa de build — o servidor é um único arquivo ESM:

git clone https://github.com/Pedro21062014/novacrm-mcp.git
cd novacrm-mcp
node test/e2e.mjs   # suíte e2e: sobe uma API v1 simulada e valida o servidor

O teste valida o protocolo completo (initialize, tools/list, tools/call de leitura e escrita, prompts, erros, lote JSON-RPC e execução sem chave).

Licença

MIT © NovaCRM