Skip to main content
Glama
perfex-crm-mcp

perfex-crm-mcp

by yunyminaya

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.

Related MCP server: GLPI MCP

🔧 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

Available Tools

4 tools
create_leadCrear lead en Perfex CRMA

Crea un lead (cliente potencial) en Perfex CRM vía el formulario web-to-lead. Requiere PERFEX_URL y PERFEX_FORM_KEY configurados. Devuelve success true/false.

Inputs: name (required), city, email, state, +6 more.

create_ticketCrear ticket de soporte en Perfex CRMA

Crea un ticket de soporte en Perfex CRM vía el endpoint público /forms/ticket. Requiere PERFEX_URL. Requiere department (o PERFEX_TICKET_DEPARTMENT).

Inputs: name (required), email (required), message (required), subject (required), +2 more.

perfex_healthComprobar conexión con Perfex CRMA

Verifica que la URL de Perfex responde. Útil para diagnosticar si el CRM está accesible.

Inputs: no named parameters.

request_quoteSolicitar presupuesto en Perfex CRMA

Envía una solicitud de presupuesto (estimate request) vía el formulario público. Requiere PERFEX_URL y PERFEX_QUOTE_KEY.

Inputs: name (required), email (required), customFields.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: lead creation, ticket creation, quote request, and health check. There is no overlap or ambiguity between them.

    Naming Consistency3/5

    Two tools follow a 'create_<entity>' pattern, but 'request_quote' uses a different verb and 'perfex_health' is not verb-first. The naming is readable but not fully consistent.

    Tool Count5/5

    Four tools is well within the ideal range for a focused CRM integration covering public form submissions and a health check. Each tool has a clear purpose and none are redundant.

    Completeness4/5

    The tool surface covers the main public-facing actions (lead, ticket, quote) and a health check. Minor gaps exist (e.g., no contact creation or read operations), but the scope of public forms is well covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A comprehensive MCP server that connects AI assistants to GoHighLevel CRM, enabling management of contacts, conversations, calendars, pipelines, payments, and more through 60+ tools.
      64
      37 npm
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      MCP server allowing an AI assistant to interact directly with your GLPI instance via its REST API, enabling ticket management, knowledge base operations, and statistics.
      40
      4
      -
    • A
      license
      B
      quality
      D
      maintenance
      Self-hosted MCP server that connects AI assistants to Kommo CRM (API v4), enabling real-time CRM actions such as creating/managing leads, tasks, notes, and more through 29 tools.
      29
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A comprehensive MCP server that connects AI systems to GoHighLevel CRM, providing 269+ tools for contact management, messaging, calendar, sales, and automation.
      10 npm
      MIT