perfex-crm-mcp

Servidor MCP (Model Context Protocol) que conecta cualquier IA con tu Perfex CRM — sin API keys, usando los endpoints públicos de Perfex (/forms/wtl, /forms/ticket, /forms/quote).

🧠 ¿Qué inteligencias conecta?

IA	Cómo se conecta
Claude (Desktop / Claude Code)	claude mcp add
Codex (OpenAI CLI)	codex mcp add
Hermes Agent (Nous Research)	configuración MCP del agente
Paperclip	adapter MCP / claude_local con MCP config

Todas usan el mismo protocolo estándar MCP → una sola integración, cuatro inteligencias.

🔧 Herramientas expuestas

Sin API key (endpoints públicos)

Herramienta	Qué hace	Endpoint Perfex
create_lead	Crea un lead (cliente potencial)	POST /forms/wtl/{key}
create_ticket	Crea un ticket de soporte	POST /forms/ticket
request_quote	Solicita un presupuesto	POST /forms/quote/{key}
perfex_health	Comprueba que el CRM responde	GET /

Con API REST completa (PERFEX_API_KEY o PERFEX_MCP_TOKEN)

Herramienta	Qué hace
list_leads	Lista leads (filtro por nombre/email/empresa)
create_lead_api	Crea lead con todos los campos (estado, responsable, fuente...)
list_clients	Lista clientes
create_client	Crea cliente + contacto primario
list_invoices	Lista facturas (filtro por estado)
list_payments	Lista pagos
list_projects	Lista proyectos
list_tasks	Lista tareas
create_task	Crea tarea (en proyecto opcional)
crm_stats	Estadísticas: leads, clientes, facturas, pagos, proyectos, tareas

📦 Instalación

git clone https://github.com/yunyminaya/perfex-crm-mcp.git
cd perfex-crm-mcp
npm install
npm run build

⚙️ Configuración (env vars)

Variable	Obligatoria	Descripción
PERFEX_URL	✅	Base del CRM, ej: https://crm.example.com
PERFEX_FORM_KEY	para leads	Key del formulario web-to-lead (forms/wtl/{key})
PERFEX_QUOTE_KEY	para quotes	Key del formulario de presupuestos
PERFEX_API_KEY	para API completa	API key del módulo REST oficial (CodeCanyon #25278359)
PERFEX_MCP_TOKEN	para API completa	Token del Mcp_api.php casero (perfex-module/, gratis)
PERFEX_LEAD_SOURCE	no	Fuente por defecto de leads (default MCP)
PERFEX_TICKET_DEPARTMENT	no	Departamento por defecto para tickets
PERFEX_TICKET_PRIORITY	no	Prioridad por defecto para tickets
PERFEX_TIMEOUT_MS	no	Timeout (default 15000)

Dos formas de activar la API REST completa (elige una):

1. Módulo oficial de CodeCanyon (REST API for Perfex CRM, #25278359) → genera API key en Perfex admin → API → define PERFEX_API_KEY. Da las 181 operaciones del módulo.
2. Mcp_api.php incluido (gratis) → copia perfex-module/Mcp_api.php a application/controllers/, define MCP_API_TOKEN en app-config.php, y usa PERFEX_MCP_TOKEN. Cubre leads, clientes, facturas, pagos, proyectos, tareas y stats.

Cómo conseguir PERFEX_FORM_KEY: Perfex admin → Leads → Web Forms → crear formulario → copiar la key (último segmento de la URL forms/wtl/{key}).

🔌 Conectar cada IA

Claude Desktop

// claude_desktop_config.json
{
  "mcpServers": {
    "perfex-crm": {
      "command": "node",
      "args": ["/ruta/a/perfex-crm-mcp/dist/index.js"],
      "env": {
        "PERFEX_URL": "https://crm.example.com",
        "PERFEX_FORM_KEY": "tu-key"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add perfex-crm -- node /ruta/a/perfex-crm-mcp/dist/index.js
# o con env:
claude mcp add perfex-crm --env PERFEX_URL=https://crm.example.com --env PERFEX_FORM_KEY=tu-key -- node /ruta/a/perfex-crm-mcp/dist/index.js

Codex (OpenAI CLI)

codex mcp add perfex-crm -- node /ruta/a/perfex-crm-mcp/dist/index.js

Hermes Agent

Añade el servidor en la config MCP de Hermes (~/.hermes/config.yaml o el gestor de MCP del agente):

mcp:
  servers:
    perfex-crm:
      command: node
      args: ["/ruta/a/perfex-crm-mcp/dist/index.js"]
      env:
        PERFEX_URL: "https://crm.example.com"
        PERFEX_FORM_KEY: "tu-key"

Paperclip

Configura el servidor MCP en el adapter del agente (adapterConfig → mcpServers), igual que Claude Code — los agentes Paperclip que usan claude_local heredan los MCP configurados.

🚀 Uso

Tras conectar, cualquiera de las IAs puede hacer:

"Crear un lead en el CRM: Juan Pérez, juan@empresa.com, tel 555-1234, interesado en facturación"
→ create_lead { name: "Juan Pérez", email: "juan@empresa.com", ... }

"Crear un ticket: María no recibe los emails de factura"
→ create_ticket { name: "María", email: "...", subject: "...", message: "..." }

"¿El CRM está accesible?"
→ perfex_health

⚠️ Notas

• Sin API keys: usa los endpoints públicos de Perfex (Web-to-Lead / tickets). Si el formulario tiene reCAPTCHA activado, las IAs no podrán crearlo — desactívalo en el formulario.
• Content-Type: los endpoints exigen application/x-www-form-urlencoded (no JSON).
• Tickets: exigen header X-Requested-With: XMLHttpRequest (ya lo envía el servidor).
• 422 = campos requeridos faltantes: revisa qué campos marca el formulario como obligatorios.

📁 Estructura

perfex-crm-mcp/
├── src/
│   ├── index.ts          # Servidor MCP (herramientas)
│   └── perfex-client.ts  # Cliente de endpoints públicos de Perfex
├── package.json
├── tsconfig.json
└── README.md