What can you do with this server?

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 (requires PERFEX_URL and PERFEX_FORM_KEY). * Create a Support Ticket (create_ticket) – Open a support ticket using name, email, subject, and message (requires PERFEX_URL). * Request a Quote (request_quote) – Submit a quote request through the public form (requires PERFEX_URL and PERFEX_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.

How do I use perfex-crm-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by yunyminaya

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

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

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.
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.

ParametersJSON Schema

Name	Required	Description
`city`	No	Ciudad
`name`	Yes	Nombre del lead (obligatorio)
`email`	No	Email
`state`	No	Estado/región
`source`	No	Fuente del lead (default: MCP)
`company`	No	Empresa
`country`	No	País (ID numérico o nombre)
`website`	No	Sitio web
`description`	No	Descripción / notas
`phonenumber`	No	Teléfono

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the burden. It discloses the mechanism (web-to-lead), required configuration, and return value (success true/false). This adds useful behavioral context beyond a simple creation statement, though it does not elaborate on failure modes or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the purpose, and includes requirements and return information. Every sentence earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (10 params, 1 required) and no output schema, the description adequately covers purpose, mechanism, requirements, and return. It does not explain error handling or duplicate behavior, which could be useful, but is not critical for a basic create lead tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional parameter-specific details beyond mentioning the web-to-lead form, which hints at mapping but does not enrich semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Crea un lead (cliente potencial) en Perfex CRM vía el formulario web-to-lead.' This identifies the specific verb (crea), resource (lead en Perfex CRM), and method (web-to-lead). It distinguishes from siblings like create_ticket and request_quote.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool (when creating a lead in Perfex CRM) and mentions prerequisites (PERFEX_URL and PERFEX_FORM_KEY configurados). It does not explicitly name alternatives or exclusion cases, but the context is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Nombre del cliente (obligatorio)
`email`	Yes	Email del cliente (obligatorio)
`message`	Yes	Mensaje/detalle del problema (obligatorio)
`subject`	Yes	Asunto del ticket (obligatorio)
`priority`	No	ID de prioridad (default: PERFEX_TICKET_PRIORITY)
`department`	No	ID del departamento (default: PERFEX_TICKET_DEPARTMENT)

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the use of a public endpoint and required environment variables/department, which is useful. With no annotations provided, it does not mention failure modes, idempotency, or response behavior, leaving some transparency gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with two sentences covering purpose, endpoint, and requirements. No filler, front-loaded, and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the essentials—purpose, endpoint, requirements—but lacks information about response format, error handling, or expected outcomes after creation. Since there is no output schema, the description leaves a notable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond emphasizing the department requirement and defaults already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a support ticket in Perfex CRM via the public endpoint /forms/ticket. This is specific and distinguishes it from sibling tools like create_lead and request_quote.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context for when to use the tool—creating a support ticket—and lists prerequisites (PERFEX_URL, department). However, it does not explicitly name alternatives or exclusions, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

perfex_healthComprobar conexión con Perfex CRMA

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

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It states that the tool verifies the URL responds, which implies a network call, but it does not disclose details such as timeout behavior, expected HTTP status, or authentication requirements. Adequate for a simple health check but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loaded with the action ('Verifica que la URL de Perfex responde') and followed by the diagnostic use case. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple health-check tool with no parameters and no output schema, the description covers the core purpose and diagnostic context. It does not explain the return format, but that is acceptable given the low complexity and the clear indication that it checks accessibility.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100%. The description correctly avoids adding parameter details; the baseline of 4 for zero-parameter tools applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Verifica que la URL de Perfex responde' clearly specifies a health-check verb (verifica) and resource (the Perfex URL), distinguishing it from sibling tools that create leads, tickets, or quotes. The title 'Comprobar conexión con Perfex CRM' reinforces the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states it is 'Útil para diagnosticar si el CRM está accesible', providing clear context for when to use this tool. It does not explicitly mention exclusions or alternatives, but the sibling tools are fundamentally different actions (create/request), so the decision context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Nombre (obligatorio)
`email`	Yes	Email (obligatorio)
`customFields`	No	Campos personalizados: { 'form-cf-5': 'valor' }

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the mechanism (public form) and the required environment variables, but does not describe side effects, return behavior, or what happens after submission. This is a moderate amount of detail for a simple request tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no fluff. It front-loads the purpose and adds a necessary prerequisite, earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple, but there is no output schema and the description does not explain what happens after submission or what the response indicates. It covers purpose and prerequisites but lacks post-condition details, making it incomplete for an agent relying solely on this description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers 100% of parameter descriptions, and the description does not add extra meaning to the parameters beyond what is already in the schema. The mention of PERFEX_URL and PERFEX_QUOTE_KEY refers to environment variables, not user-supplied parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Envía una solicitud de presupuesto') and the resource ('estimate request' via public form). It distinguishes itself from sibling tools like create_lead and create_ticket by being quote-specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like create_lead or create_ticket. The description only mentions a prerequisite (PERFEX_URL and PERFEX_QUOTE_KEY) but does not explain the ideal use case or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

4 tool updatesv1.0.0Aug 9, 2026
- First observedcreate_lead
- First observedcreate_ticket
- First observedperfex_health
- First observedrequest_quote

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Scored 2026-08-09 21:10 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

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Artificial Wit AIOAuth
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
OneSchema MCP Server
co.oneschema
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Data Platforms App Automation
1
anythingmcp B
io.github.keysersoft
Self-hosted MCP gateway: turn any API, database or MCP server into AI connectors — no code.
Agent Orchestration Data Platforms App Automation
42200
ZapierOAuth
com.zapier
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
App Automation Workplace & Productivity
2297

Related MCP Servers

GHL MCP Server
CRM Communication
northrosetech
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.
Updated 5 months ago (2026-04-23 06:56 UTC)
64
39
1
MIT
GLPI MCP
Customer Support Knowledge & Memory
svtica
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.
Updated 3 days ago (2026-09-09 18:28 UTC)
40
4
-
invoiceninja-mcp
Finance CRM Payments & Billing
ambaloo
A
license
B
quality
D
maintenance
MCP server for Invoice Ninja v5 API. Enables AI assistants to manage clients, invoices, quotes, payments, and time tracking through natural language.
Updated 8 months ago (2026-01-23 14:26 UTC)
32
16
2
MIT
kommo-mcp
CRM Autonomous Agents
RonaldoESantosRevOps
A
license
B
quality
C
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.
Updated 2 months ago (2026-07-07 22:02 UTC)
29
1
MIT