Servidor MCP de RepairDesk

Un servidor MCP (Model Context Protocol) que da a cualquier asistente de IA compatible con MCP — Claude Code, Claude Desktop, Codex CLI, OpenCode, Cursor, Windsurf, o cualquier otro cliente MCP — acceso directo de lectura/escritura a los datos de tu tienda RepairDesk. Apúntalo a la clave API de tu tienda y empieza a preguntar cosas como "busca el ticket T-15423", "¿qué está pendiente en la factura 8821?", o "asigna el trabajo de pantalla del iPhone a Dave".

No es un producto oficial de RepairDesk — es una herramienta independiente creada por una tienda RepairDesk para tiendas RepairDesk. Sin garantía, úsalo bajo tu propio riesgo (ver Licencia) — pero está en uso diario gestionando la cola de tickets de una tienda de reparación real, no una prueba de concepto.

Contenido

• Lo que realmente puedes hacer con esto

• Referencia de herramientas

• Lo que esto no es

• Inicio rápido

• Configuración manual

• Todas las opciones de configuración

• Solución de problemas

• Preguntas frecuentes

• Seguridad

Related MCP server: TicketAI

Lo que realmente puedes hacer con esto

Una vez conectado a tu asistente de IA, puedes simplemente hablar con tus datos de RepairDesk en lugar de hacer clic en la interfaz web. Algunos ejemplos reales:

Mostrador / triaje

• "Busca el ticket T-15423" — detalle completo del ticket: cliente, dispositivo, estado por dispositivo, notas.

• "¿Cuál es el estado del teléfono de Sarah Miller?" — busca tickets por nombre/palabra clave del cliente.

• "Muéstrame todo lo que esté Pendiente o Esperando piezas" — filtra tickets por estado.

• "¿Qué tiene asignado Dave ahora mismo?" — filtra tickets por técnico.

• "Saca los datos de contacto de John" — búsqueda de clientes por nombre, teléfono o correo electrónico.

Flujo de trabajo / trabajo en banco

• "Añade una nota de diagnóstico a T-15423: pantalla reemplazada, batería probada OK"

• "Asigna el ticket T-15490 a Dave"

• "Marca T-15423 como Reparado" — el servidor te pedirá confirmación primero, y avisa de que este estado dispara automáticamente un SMS/correo al cliente en RepairDesk.

• "Crea un ticket para este cliente: iPhone 13, reemplazo de pantalla" — de nuevo, se requiere confirmación antes de crear nada realmente.

Dinero / administración

• "¿Qué facturas siguen sin pagar del mes pasado?"

• "¿Cuál es el saldo pendiente de la factura 8821?"

• "¿Tenemos una batería de iPhone 13 en stock?" — búsqueda de inventario.

• "Lista todos nuestros técnicos" / "¿Qué métodos de pago tenemos configurados?"

• "¿Qué categorías de reparación/tipos de dispositivo tenemos configurados?" — contexto útil al crear un ticket o diagnosticar qué modelo de dispositivo es en tu sistema.

Como esto funciona a través de un asistente de IA real en lugar de un panel fijo, puedes encadenar estas acciones de forma natural — "encuentra facturas vencidas de clientes con un ticket aún abierto" — y el asistente lo resuelve entre herramientas en lugar de que tú cruces dos pantallas manualmente.

Referencia de herramientas

Barra de seguridad: repairdesk_tickets_write requiere confirmed: true antes de aplicar un cambio de estado, y avisa cuando el estado objetivo es uno sobre el que RepairDesk notifica automáticamente al cliente (Reparado, Listo para recoger, Completado, Esperando al cliente, Esperando presupuesto, Cancelado). No necesitas hacer nada para que esto funcione — solo responde "sí" cuando tu asistente transmita la solicitud de confirmación.

Detalle útil: las búsquedas/escrituras de tickets aceptan tanto el formato de ID de pedido de RepairDesk (T-15423) como el ID numérico interno del ticket — nunca necesitas saber cuál tienes, el servidor lo resuelve por ti.

Lo que esto no es

Esto cubre el lado de lectura de RepairDesk más las escrituras básicas del flujo de trabajo de tickets. No cubre presupuestos, creación de citas, transacciones de POS/ventas, escrituras de inventario, registro de pagos, subida de imágenes/adjuntos de tickets, ni webhooks. Se aceptan PRs si necesitas alguna de esas funciones.

Inicio rápido

No necesitas ser desarrollador para ejecutar esto — solo sentirte cómodo escribiendo un puñado de comandos en una terminal. Tiempo total: unos 5 minutos.

1. Instala Node.js (si no lo tienes)

Descárgalo e instálalo desde nodejs.org — elige la versión "LTS". Esto instala tanto node como npm. Para comprobar que funcionó, abre una terminal y ejecuta:

node --version

Deberías ver algo como v20.x.x (cualquier versión 18 o superior está bien).

2. Obtén el código

Si tienes Git:

git clone https://github.com/codeyoc/repairdesk-mcp.git
cd repairdesk-mcp

Si no: haz clic en el botón verde Code en la página del repositorio de GitHub → Download ZIP → descomprímelo en algún lugar → abre una terminal en esa carpeta.

3. Obtén tu clave API de RepairDesk

En tu administración de RepairDesk: Settings → API. Copia la clave que se muestra allí — el script de configuración te la pedirá en el siguiente paso. Trátala como una contraseña: otorga acceso completo de lectura/escritura a los datos de tu tienda (ver Seguridad).

4. Ejecuta el script de configuración

node setup.mjs

Este es el camino más rápido y se encarga de todo: ejecuta npm install por ti si es necesario, te pide tu clave API, pregunta qué asistente de IA estás usando (Claude Code, Claude Desktop, Codex CLI, o OpenCode), y escribe la configuración automáticamente — haciendo una copia de seguridad de cualquier archivo de configuración existente primero. Si estás en otro, imprime el bloque de configuración para que lo pegues tú mismo.

Si prefieres hacerlo a mano — o tu cliente no es uno de los cuatro anteriores — consulta Configuración manual a continuación. De cualquier manera, ejecuta npm install tú mismo primero si omites el script.

5. Pruébalo

Pregunta a tu asistente algo como "Usando RepairDesk, lista mis 5 tickets más recientes". Si responde con datos reales de tickets, has terminado.

Configuración manual

Omite esto si node setup.mjs ya funcionó para ti. De lo contrario, ejecuta npm install en esta carpeta primero, y luego conecta tu cliente a mano:

Ejecuta esto desde cualquier lugar, reemplazando la ruta con la ruta completa a donde descomprimiste/clonaste la carpeta, y la clave con la tuya real:

claude mcp add repairdesk \
  --env REPAIRDESK_API_KEY=your_key_here \
  --env REPAIRDESK_USER_AGENT=YourShopName-MCP/1.0 \
  -- node /full/path/to/repairdesk-mcp/server.mjs

Abre (o crea) el archivo de configuración para tu sistema operativo:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Añade esto (combínalo con lo que ya haya en mcpServers si el archivo no está vacío):

{
  "mcpServers": {
    "repairdesk": {
      "command": "node",
      "args": ["/full/path/to/repairdesk-mcp/server.mjs"],
      "env": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

Guarda el archivo, luego cierra y vuelve a abrir completamente Claude Desktop (no solo cierres la ventana).

Edita (o crea) ~/.codex/config.toml y añade:

[mcp_servers.repairdesk]
command = "node"
args = ["/full/path/to/repairdesk-mcp/server.mjs"]

[mcp_servers.repairdesk.env]
REPAIRDESK_API_KEY = "your_key_here"
REPAIRDESK_USER_AGENT = "YourShopName-MCP/1.0"

Inicia una nueva sesión de Codex y ejecuta /mcp para confirmar que se conectó. (Codex también tiene un comando interactivo codex mcp add si prefieres eso a editar el archivo — consulta codex mcp add --help para las banderas exactas en tu versión instalada.)

Abre (o crea) el archivo de configuración para tu sistema operativo:

• Mac/Linux: ~/.config/opencode/opencode.json

• Windows: %APPDATA%\opencode\opencode.json

Añade esto (combínalo con lo que ya haya en mcp si el archivo no está vacío):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "repairdesk": {
      "type": "local",
      "command": ["node", "/full/path/to/repairdesk-mcp/server.mjs"],
      "enabled": true,
      "environment": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

Reinicia OpenCode para que lo recoja.

La forma command/args/env usada arriba (Claude Code/Desktop) es el estándar de facto — la mayoría de los clientes MCP la siguen, solo que en un archivo de configuración diferente. Consulta la documentación de tu cliente para saber dónde está ese archivo; el bloque en sí debería funcionar tal cual.

Usa la ruta completa y absoluta a server.mjs (por ejemplo, /Users/you/repairdesk-mcp/server.mjs o C:\Users\you\repairdesk-mcp\server.mjs) — una ruta relativa fallará porque tu cliente de IA no se ejecuta desde dentro de esta carpeta.

Todas las opciones de configuración

Todo lo siguiente va en el bloque env/environment que usa la configuración de tu cliente (setup.mjs lo maneja por ti) — no en un archivo .env, ya que la mayoría de los clientes MCP no lo leen automáticamente. .env.example en este repositorio lista las mismas variables como referencia.

Alternativa: archivo de configuración en lugar de variables de entorno. Si tu configuración hace que las variables de entorno sean incómodas, crea un config.json (ignorado por git) junto a server.mjs:

{
  "repairdesk_api_key": "your_key_here",
  "repairdesk_base_url": "https://api.repairdesk.co/api/web/v1"
}

Se vuelve a leer en cada llamada a la API, así que puedes rotar la clave sin reiniciar el servidor. Las variables de entorno tienen prioridad sobre este archivo cuando ambos están presentes.

Límite de velocidad: lo de 100/minuto

El límite documentado de RepairDesk es de 100 solicitudes por minuto por clave de API (algunos planes permiten hasta 120; comprueba tu propio plan si no estás seguro). Este servidor lo maneja automáticamente por ti:

• Cada llamada saliente se pone en cola a través de un único limitador que espera al menos REPAIRDESK_MIN_INTERVAL_MS (por defecto 600 ms ≈ 100/min) entre solicitudes, de modo que pedir un gran lote de tickets no provocará por sí mismo un error de límite de velocidad.

• Si RepairDesk aún devuelve un 429 (límite de velocidad alcanzado), por ejemplo, si otra herramienta también está golpeando la misma clave, el servidor espera automáticamente y reintenta una vez antes de rendirse.

• No necesitas configurar nada para que esto funcione. Solo toca REPAIRDESK_MIN_INTERVAL_MS si ves errores de límite de velocidad de forma constante (súbelo) o si sabes que tu plan permite un límite más alto y quieres búsquedas masivas más rápidas (bájalo, con cuidado).

Solución de problemas

"RepairDesk API returned 401 Unauthorized" / "Unauthorized" en la respuesta Tu clave de API es incorrecta, fue revocada o no se recogió. Vuelve a comprobar la clave en Configuración → API en RepairDesk, y que esté escrita correctamente en la configuración de tu cliente MCP (sin un espacio suelto, y que no siga siendo YOUR_REPAIRDESK_API_KEY_HERE). Reinicia completamente tu cliente de IA después de cualquier cambio de configuración; la mayoría no recarga la configuración de MCP en vivo.

Las solicitudes fallan inmediatamente / parecen estar bloqueadas, no autenticadas El Cloudflare de RepairDesk bloquea solicitudes con un User-Agent vacío o con apariencia predeterminada. No establezcas REPAIRDESK_USER_AGENT como una cadena vacía.

"RepairDesk API rate limit hit twice in a row (429)" Estás haciendo solicitudes más rápido de lo que permite tu clave incluso después del reintento integrado. Sube REPAIRDESK_MIN_INTERVAL_MS (prueba con 1000) en tu configuración.

"Ticket T-XXXXX not found — could not resolve to internal ID" Comprueba que el ID del pedido sea correcto y que exista en esta tienda de RepairDesk. Si tienes el ID numérico interno, también funciona: pásalo directamente.

"RepairDesk API request timed out after 15000ms" Normalmente es un problema de red/firewall para llegar a api.repairdesk.co, o REPAIRDESK_BASE_URL es incorrecto. Comprueba que puedes alcanzar ese host desde donde se ejecuta este servidor.

Tu asistente de IA no ve la herramienta en absoluto

• Confirma que la ruta en args es absoluta, no relativa, y que apunta realmente a server.mjs.

• Confirma que ejecutaste npm install en esa carpeta (si falta node_modules, el servidor no puede arrancar).

• Cierra y reinicia por completo tu cliente de IA; no basta con cerrar la ventana de chat.

• Ejecuta node /ruta/completa/a/server.mjs directamente en una terminal; si da error, verás el problema real en lugar de un "herramienta no disponible" genérico de tu cliente.

node setup.mjs dice que no pudo encontrar claude/codex en tu PATH No pasa nada: recurre a imprimir el bloque de configuración para que lo pegues manualmente (consulta Configuración manual). Esto solo significa que esa CLI no está instalada o no está en tu PATH; no significa que el servidor MCP en sí esté roto.

¿Sigue atascado? Abre un issue en este repositorio con el mensaje de error (redacta tu clave de API primero si aparece en algún lugar de la salida).

Preguntas frecuentes

¿Es esta una herramienta oficial de RepairDesk? No. Está construida y mantenida de forma independiente, utilizando la API pública de RepairDesk. Úsala bajo tu propio criterio.

¿Cuesta algo ejecutarla? No: solo realiza las mismas llamadas a la API que tu plan de RepairDesk ya permite. No hay ninguna tarifa adicional de este proyecto. (Tu suscripción de asistente de IA, por ejemplo Claude, es separada y no está relacionada con este servidor).

¿Puedo usar esto con algo que no sea Claude? Sí: MCP es un estándar abierto. setup.mjs configura Claude Code, Claude Desktop, Codex CLI y OpenCode directamente; cualquier otra cosa que hable MCP sobre stdio (Cursor, Windsurf, etc.) también puede usar este servidor, mediante la configuración manual en Configuración manual.

¿Puedo ejecutar esto para varias tiendas de RepairDesk? Sí: regístralo varias veces con diferentes nombres (por ejemplo, repairdesk-store1, repairdesk-store2) en tu cliente MCP, cada uno con su propia REPAIRDESK_API_KEY.

¿Mi asistente de IA enviará accidentalmente correos o mensajes de texto a mis clientes? Solo repairdesk_tickets_write puede provocar eso, y solo mediante un cambio de estado, que siempre requiere un confirmed: true explícito y se marca en la descripción de la herramienta cuando el estado objetivo es uno de los estados notificadores de RepairDesk. No ocurrirá en silencio.

Seguridad

Tu REPAIRDESK_API_KEY otorga acceso completo de lectura/escritura a los datos de clientes y financieros de tu tienda. Mantenla en la configuración de entorno de tu cliente MCP, nunca en un archivo versionado. config.json y .env están ignorados por git aquí precisamente por esa razón: úsalos localmente si prefieres un archivo en lugar de variables de entorno, pero no subas una copia rellenada. ¿Encontraste un problema de seguridad? Abre un issue (o un informe privado si tu host lo permite) en lugar de un PR público con detalles del exploit.

Licencia

MIT: consulta LICENSE. Se proporciona tal cual, sin garantía: eres responsable de cómo lo usas con tu propia cuenta de RepairDesk.