perfex-crm-mcp
This MCP server allows AI assistants to interact with a Perfex CRM instance through public endpoints (no API key required) and, optionally, via REST API with credentials.
Public endpoints (no API key required):
Create a Lead (
create_lead) – Submit a potential client via the web-to-lead form (requiresPERFEX_URLandPERFEX_FORM_KEY).Create a Support Ticket (
create_ticket) – Open a support ticket using name, email, subject, and message (requiresPERFEX_URL).Request a Quote (
request_quote) – Submit a quote request through the public form (requiresPERFEX_URLandPERFEX_QUOTE_KEY).Check CRM Health (
perfex_health) – Verify the CRM instance is reachable.
With REST API key or MCP token:
Leads: List and create leads with custom fields.
Clients: List and create clients/contacts.
Finances: List invoices and payments.
Projects/Tasks: List projects, list and create tasks.
Statistics: Get counts of leads, clients, invoices, payments, projects, and tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@perfex-crm-mcp Create a lead in the CRM for Jane, email jane@example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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) |
|
Codex (OpenAI CLI) |
|
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 |
| Crea un lead (cliente potencial) |
|
| Crea un ticket de soporte |
|
| Solicita un presupuesto |
|
| Comprueba que el CRM responde |
|
Con API REST completa (PERFEX_API_KEY o PERFEX_MCP_TOKEN)
Herramienta | Qué hace |
| Lista leads (filtro por nombre/email/empresa) |
| Crea lead con todos los campos (estado, responsable, fuente...) |
| Lista clientes |
| Crea cliente + contacto primario |
| Lista facturas (filtro por estado) |
| Lista pagos |
| Lista proyectos |
| Lista tareas |
| Crea tarea (en proyecto opcional) |
| 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 |
| ✅ | Base del CRM, ej: |
| para leads | Key del formulario web-to-lead ( |
| para quotes | Key del formulario de presupuestos |
| para API completa | API key del módulo REST oficial (CodeCanyon #25278359) |
| para API completa | Token del Mcp_api.php casero (perfex-module/, gratis) |
| no | Fuente por defecto de leads (default |
| no | Departamento por defecto para tickets |
| no | Prioridad por defecto para tickets |
| no | Timeout (default 15000) |
Dos formas de activar la API REST completa (elige una):
Módulo oficial de CodeCanyon (
REST API for Perfex CRM, #25278359) → genera API key en Perfex admin → API → definePERFEX_API_KEY. Da las 181 operaciones del módulo.Mcp_api.php incluido (gratis) → copia
perfex-module/Mcp_api.phpaapplication/controllers/, defineMCP_API_TOKENenapp-config.php, y usaPERFEX_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.jsCodex (OpenAI CLI)
codex mcp add perfex-crm -- node /ruta/a/perfex-crm-mcp/dist/index.jsHermes 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.mdAvailable Tools
4 toolscreate_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseBqualityDmaintenanceA comprehensive MCP server that connects AI assistants to GoHighLevel CRM, enabling management of contacts, conversations, calendars, pipelines, payments, and more through 60+ tools.6437 npm1MIT
- AlicenseBqualityCmaintenanceMCP server allowing an AI assistant to interact directly with your GLPI instance via its REST API, enabling ticket management, knowledge base operations, and statistics.404-
- AlicenseBqualityDmaintenanceSelf-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.291MIT
- AlicenseNot gradedqualityCmaintenanceA comprehensive MCP server that connects AI systems to GoHighLevel CRM, providing 269+ tools for contact management, messaging, calendar, sales, and automation.10 npmMIT