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?

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

Related MCP server: GLPI MCP

🔧 Herramientas expuestas

Sin API key (endpoints públicos)

Con API REST completa (PERFEX_API_KEY o PERFEX_MCP_TOKEN)

📦 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)

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