Simpro MCP server

No oficial. Este es un proyecto independiente de terceros. No está afiliado a, respaldado por, ni cuenta con el apoyo de Simpro.

Permite que un agente de IA trabaje con tu cuenta de Simpro. Busca casi cualquier cosa en Simpro y reúne cifras que normalmente significarían hacer clic en varias pantallas. Tú preguntas en inglés sencillo; el agente hace las búsquedas y los cambios en Simpro por ti.

Alcanza todas las partes de la API de Simpro, así que aunque no exista una herramienta específica para algo, el agente puede acceder igualmente.

⚠️ Esta herramienta puede escribir y borrar, no solo leer. Accede a la API completa de Simpro, incluidos los endpoints que actualizan y eliminan registros. Un agente de IA que la maneje puede, por error o por seguir una instrucción incorrecta, modificar o destruir presupuestos, trabajos, clientes, artículos del catálogo y más en tu cuenta real de Simpro, de forma masiva y sin deshacer. Actúa con los permisos que tenga la clave o el inicio de sesión que le entregues. No se la des a un agente en el que no confíes, no la dejes ejecutarse sin supervisión contra producción, y dale un inicio de sesión/clave de Simpro limitado solo a lo que realmente necesite. Si quieres seguridad de solo lectura, crea un usuario de Simpro con permisos de solo lectura y autentícate como ese usuario.

Esto se desarrolló a partir de una herramienta interna que usamos y que se encuentra detrás de nuestra propia puerta de enlace MCP. Añadimos algunas funciones adicionales para hacerla un poco más útil para la comunidad, pero el modo mcbp y el modo OAuth Broker no los usamos internamente.

Este software se proporciona "tal cual", sin garantía de ningún tipo, ya sea expresa o implícita. Lo usas bajo tu propio riesgo; los autores no aceptan ninguna responsabilidad por pérdidas, daños o cambios realizados en tus datos de Simpro por su uso.

Requisitos previos

• Para la instalación en Claude Desktop (opción 1): solo necesitas Claude Desktop y una app OAuth de Simpro: el paquete .mcpb incluye su propio runtime.

• Para ejecutar desde el código fuente o autoalojar (opciones 2 y 3): Node.js 24 o superior y npm.

• Un build de Simpro al que puedas acceder y una app OAuth (o clave de API heredada) creada en él; la sección de cada modo indica exactamente qué necesita.

Related MCP server: ServiceTitan MCP Server

Contenido

• Instalar en Claude Desktop (la forma sencilla)

  • Qué necesitas de Simpro

  • Instalación

  • Iniciar sesión (el flujo OAuth)

  • Otras formas de autenticarse

  • Ejecutarlo localmente desde el código fuente

• Modo OAuth Broker (para el conector de agentes de IA)

• Modo Proxy HTTP (para una configuración compartida/alojada)

• ¿Qué modo quiero?

• Conectar un cliente (fragmentos de configuración)

• Cómo el broker mejora el inicio de sesión de Simpro

• Crearlo tú mismo

1. Instalar en Claude Desktop (la forma sencilla)

Nada de línea de comandos, nada de archivos de configuración. Instalas el paquete .mcpb desde los ajustes de extensiones de Claude Desktop, rellenas un formulario breve e inicias sesión en Simpro una vez en tu navegador. Después, el agente se mantiene conectado y solo tienes que chatear.

Qué necesitas de Simpro

Te autenticas con una app OAuth de Simpro, que te identifica mediante la propia pantalla de inicio de sesión de Simpro: es la forma recomendada. Créala en Simpro en Setup → Integrations → API → New API Key (elige una aplicación OAuth / "Authorization Code") y anota:

Un paso importante: en tu app OAuth de Simpro, establece la Redirect URI en http://localhost:8237/callback. Ahí es donde Simpro te devuelve después de iniciar sesión. Debe coincidir exactamente. Si el puerto 8237 ya está en uso en tu máquina, elige otro y pon el Auth redirect port correspondiente en la pantalla de instalación; pero la redirect URI registrada debe usar el mismo puerto.

Instalación

1. Descarga el archivo simpro-mcp-server.mcpb más reciente desde la página de Releases.

2. En Claude Desktop, abre Settings → Extensions, haz clic en Advanced settings y luego en Install extension (puede que primero tengas que habilitar las instalaciones de desarrollador/extensiones allí). Selecciona el archivo simpro-mcp-server.mcpb que descargaste. Aparecerá una pantalla de instalación.

3. Rellena:

   • Build URL y Company ID

   • Authentication mode: déjalo en authorization_code (el inicio de sesión en el navegador).

   • Client ID y Client secret de tu app OAuth de Simpro.

   • Deja Auth redirect port en 8237 a menos que hayas registrado otro.

4. Haz clic en instalar.

Iniciar sesión (el flujo OAuth)

La primera vez que el agente use la herramienta, se abrirá una pestaña del navegador en la pantalla de inicio de sesión de Simpro. Inicia sesión y aprueba el acceso. La pestaña mostrará "✓ Autorizado": ciérrala y vuelve a tu chat.

Con ese único inicio de sesión te basta. La herramienta guarda en caché un token de refresco, así que permaneces conectado entre reinicios y no se te volverá a pedir hasta que ese token se revoque o caduque. Si eso ocurre, simplemente se abre de nuevo la pestaña de inicio de sesión.

Eso es todo: inicia un chat y pregunta algo como "muéstrame los presupuestos abiertos de Acme" o "¿qué hay en el trabajo 4521?".

Page size es un ajuste opcional en la pantalla de instalación. Déjalo en 50. Simplemente limita cuántas filas vuelven de una vez para que las listas grandes no saturen una sola respuesta: el agente siempre puede pedir más.

Otras formas de autenticarse

El campo Authentication mode de la pantalla de instalación ofrece tres opciones:

Mantener tus credenciales a salvo

Tu client secret, tu token de refresco y cualquier clave de API los almacena Claude Desktop y se usan solo para hablar con tu propio build de Simpro. Quien tenga acceso a ellos puede actuar en Simpro con los mismos permisos que tú has concedido, así que no compartas la instalación .mcpb ni esos valores con personas que no deban tener ese acceso. Si alguna credencial queda expuesta, revoca la app OAuth o la clave en Simpro y crea una nueva.

Ejecutarlo localmente desde el código fuente

Para desarrolladores o para cualquiera que ejecute desde un clon de Git en lugar del paquete .mcpb. Si ya instalaste la extensión de arriba, puedes omitir esto.

1. Copia .env.example → .env y define SIMPRO_BASE_URL y SIMPRO_COMPANY_ID, además de ya sea SIMPRO_CLIENT_ID + SIMPRO_CLIENT_SECRET (para el inicio de sesión en el navegador o el inicio de sesión de máquina) o SIMPRO_API_KEY (la clave heredada).

2. El modo de autenticación se deduce de lo que configures: client_credentials cuando están presentes tanto el client ID como el secret; si no, api_key. Para forzar el inicio de sesión en el navegador, define SIMPRO_AUTH_MODE=authorization_code.

3. npm install && npm run build && npm start: esto se ejecuta sobre stdio, igual que la extensión instalada.

Para el inicio de sesión en el navegador (authorization_code), puedes iniciar sesión una vez por adelantado con npm run login: abre la pestaña de inicio de sesión de Simpro y guarda el token de refresco en .simpro-tokens.json. Si lo omites, el servidor ejecuta el mismo inicio de sesión la primera vez que se usa una herramienta. Consulta Crearlo tú mismo para ver la lista completa de scripts.

2. Modo OAuth Broker (para el conector de agentes de IA)

Para conectar Simpro a un agente de IA como un conector de verdad, donde cada persona se identifica en Simpro por sí misma mediante la pantalla de inicio de sesión normal de Simpro: sin clave compartida, sin archivo de configuración por persona. Para la mayoría de la gente que ejecuta esto en un servidor, este es el modo que quieres.

Este es el modo al que recurre por defecto la configuración Docker incluida. Es el valor predeterminado más seguro: el servidor autentica a los usuarios por sí mismo en lugar de confiar en una credencial que le llegue desde el origen. Aun así, debe estar detrás de un proxy inverso que termine TLS y enrute PUBLIC_URL hacia él, pero el contenedor nunca es quien decide confiar en una cabecera entrante.

El inicio de sesión de Simpro en sí es un diseño OAuth 2.0 al que los conectores de agentes modernos no se conectan directamente. Este servidor se sitúa en medio y lo eleva al estándar OAuth 2.1 que ellos exigen: añade los pasos de seguridad que le faltan a Simpro, sin dejar de delegar en el inicio de sesión real de Simpro. Desde el punto de vista del usuario, es simplemente "haz clic en conectar, inicia sesión en Simpro". Los pasos exactos que añade están explicados en Cómo el broker mejora el inicio de sesión de Simpro más abajo.

El servidor se sitúa delante de Simpro y ejecuta el protocolo de inicio de sesión. Un usuario añade el conector en su agente, es enviado a Simpro para iniciar sesión y, a partir de ahí, el agente actúa como esa persona en Simpro. Su acceso a Simpro queda sellado dentro del token que guarda el agente; el servidor no conserva ninguna base de datos de inicios de sesión.

Este modo necesita una dirección web pública y una app OAuth de Simpro (creada en Simpro en Setup → Integrations). En esa app OAuth, establece la Redirect URL como tu dirección pública seguida de /callback, por ejemplo https://simpro.yourcompany.com/callback.

Configuración

Define estas variables de entorno, además de SIMPRO_BASE_URL (y opcionalmente SIMPRO_COMPANY_ID) de arriba.

No definas SIMPRO_API_KEY en este modo: el servidor se negará a arrancar.

3. Modo proxy HTTP (para una configuración compartida o alojada)

Para equipos que ejecutan esto en un servidor detrás de algo que ya gestiona el inicio de sesión (por ejemplo, una configuración de Cowork o Copilot). En este modo, el servidor no guarda ninguna clave de Simpro propia: cada solicitud trae su propio inicio de sesión, adjuntado por lo que sea que autentique a tus usuarios. El servidor simplemente lo reenvía a Simpro.

⚠️ No está diseñado para estar expuesto a internet. Este modo debe ejecutarse detrás de una pasarela o proxy inverso (una pasarela MCP, Context Forge, o algo como nginx/Traefik) que termine TLS y autentique a los usuarios. No realiza autenticación propia y no está endurecido para la exposición directa: nunca lo publiques directamente en internet. El contenedor, a propósito, no se publica en el host por defecto; la pasarela lo alcanza en una red privada.

Para usar este modo, define SIMPRO_TRANSPORT=proxy (la configuración de Docker incluida usa por defecto el más seguro modo broker anterior). Si despliegas con Portainer o Context Forge, consulta docs/deploy.md para ver la estructura del stack.

Aquí no definirás una clave de API; de hecho, el servidor se niega a arrancar si hay una presente, porque en este modo el inicio de sesión por usuario es lo único que debería conceder acceso.

Importante: este modo no realiza ninguna comprobación propia. Cualquier cabecera Authorization que llegue con una solicitud se reenvía directamente a Simpro, sin tocarla. El servidor no verifica que la credencial sea válida, que no haya caducado, ni que la solicitud provenga de alguien con permiso para hacerla: Simpro es lo único que decide si la credencial funciona. Esto es a propósito: este modo asume que la capa que tiene delante (la pasarela o el sistema de inicio de sesión) ya ha autenticado al usuario y ha adjuntado una cabecera de confianza. Ejecuta este modo solo detrás de una capa así. Si lo expones directamente, cualquiera que pueda alcanzarlo podrá hacer que su cabecera se pase a Simpro tal cual.

Ajustes

Se definen como variables de entorno (en tu archivo .env o mediante tu plataforma de contenedores).

No definas SIMPRO_API_KEY en este modo: el servidor se negará a arrancar.

También puedes ajustar cuántos datos vuelven de una vez:

4. ¿Qué modo quiero?

5. Conexión de un cliente (fragmentos de configuración)

La instalación .mcpb de Claude Desktop (opción 1) escribe su propia configuración: no tocarás el JSON para eso. Estos fragmentos son para ejecutar desde un checkout del código fuente o apuntar un cliente a un broker o proxy alojado.

Claude Desktop: stdio desde el código fuente

Edita claude_desktop_config.json (Ajustes → Desarrollador → Editar configuración). Apunta command a node y args al dist/index.js compilado, y pasa tus ajustes de Simpro como env:

{
  "mcpServers": {
    "simpro": {
      "command": "node",
      "args": ["/absolute/path/to/simpro-mcp/dist/index.js"],
      "env": {
        "SIMPRO_BASE_URL": "https://yourbuild.simprosuite.com",
        "SIMPRO_COMPANY_ID": "0",
        "SIMPRO_AUTH_MODE": "authorization_code",
        "SIMPRO_CLIENT_ID": "your-oauth-client-id",
        "SIMPRO_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

Compila primero (npm install && npm run build). En Windows usa una ruta completa con barras invertidas escapadas ("C:\\path\\to\\simpro-mcp\\dist\\index.js"). Para la clave heredada, quita el client id/secret y define "SIMPRO_API_KEY" en su lugar (solo stdio).

Claude Code: claude mcp add

Registra el mismo servidor stdio desde la CLI (ejecútalo desde el checkout, o usa una ruta absoluta):

claude mcp add simpro \
  --env SIMPRO_BASE_URL=https://yourbuild.simprosuite.com \
  --env SIMPRO_COMPANY_ID=0 \
  --env SIMPRO_AUTH_MODE=authorization_code \
  --env SIMPRO_CLIENT_ID=your-oauth-client-id \
  --env SIMPRO_CLIENT_SECRET=your-oauth-client-secret \
  -- node ./dist/index.js

Apuntar un cliente a un broker alojado (opción 2)

Una vez que el broker esté en marcha detrás de tu dirección pública, añádelo como conector remoto: no hay comando local ni env. Usa la interfaz de conector/"Añadir conector personalizado" de tu cliente y dale la URL MCP:

https://simpro.yourcompany.com/mcp

El cliente es enviado a Simpro para iniciar sesión; no hay nada más que configurar. (El proxy HTTP de la opción 3 se alcanza de la misma manera, pero espera que tu pasarela adjunte el bearer: no se añade como conector simple).

6. Cómo el broker mejora el inicio de sesión de Simpro

Esta sección es para los curiosos técnicos o para cualquiera que revise la seguridad del conector. No la necesitas para usar ninguno de los tres modos anteriores.

Los conectores de agente modernos solo se conectan a servidores de autorización que cumplen el estándar OAuth 2.1. El OAuth de Simpro no implementa PKCE ni admite los esquemas de identidad de cliente que usan esos conectores. En lugar de pedirle a Simpro que cambie, el broker se sitúa delante como un servidor de autorización OAuth 2.1 conforme por derecho propio, y retransmite silenciosamente a Simpro entre bastidores. Concretamente, añade:

• PKCE (S256), aplicado por nosotros. El cliente que se conecta debe enviar un desafío de código en /authorize y demostrarlo en /token; si no hay coincidencia, se rechaza. Simpro no implementa PKCE, así que el broker es quien realmente lo aplica: cierra la brecha del código de autorización robado que el 2.0 puro deja abierta.

• Identidad moderna del cliente: sin secreto compartido incrustado en el cliente. El cliente que se conecta le indica al broker quién es de una de dos maneras estándar, y el broker acepta la que utilice cada cliente:

  • CIMD (documento de metadatos de ID de cliente): el client_id es una URL que el broker obtiene y valida en cada solicitud; debe ser autorreferencial y enumerar la dirección de redirección exacta que se está utilizando. No hay nada pre-registrado. La obtención se realiza detrás de una protección anti-SSRF para que esa URL no pueda utilizarse para sondear la red interna del servidor.

  • DCR (registro dinámico de clientes, RFC 7591): un cliente puede hacer POST /register para generar su propio client_id de antemano. El broker anuncia este endpoint en sus metadatos. El registro es abierto (sin autenticación), por lo que está limitado por tasa y tamaño, y expulsa las entradas más antiguas al llegar al límite; los clientes registrados se conservan para que sobrevivan a un reinicio. Un cliente puede registrarse como público (sin secreto) o confidencial (el broker emite un secreto y luego lo exige en el paso de token).

  En cualquier caso, la identidad del cliente descendente nunca llega a Simpro: el broker mantiene un único registro fijo de Simpro y retransmite bajo esa identidad.

• Coincidencia exacta de la redirección. La dirección a la que se devuelve al cliente debe coincidir con la registrada, carácter por carácter, no solo que "empiece por".

• Tokens de corta duración y vinculados a la audiencia. El token que recibe el cliente es uno que emite el broker, marcado con una fecha de caducidad y vinculado a este servidor concreto como su audiencia. Los tokens reales de Simpro están cifrados (sellados) en su interior. El broker no mantiene ninguna base de datos de tokens: cada token es autónomo, y el token de actualización que emite tiene una vida máxima de 30 días, de modo que uno filtrado no pueda reproducirse indefinidamente. La única excepción: como Simpro rota los tokens de actualización con cada uso (cada actualización consume el anterior), el broker conserva el token de actualización vigente de Simpro por cada inicio de sesión solo en memoria, durante unos minutos, para que un cliente que pierda una respuesta de actualización no se vea obligado a iniciar sesión de nuevo. Nunca se escribe en disco; la siguiente actualización correcta —que confirma que el cliente ya posee el token actual— lo retira, y un reinicio o unos minutos de inactividad lo eliminan.

El efecto neto: el agente habla con algo que parece un proveedor OAuth 2.1 limpio y moderno, el usuario sigue iniciando sesión en la pantalla auténtica de Simpro, y las partes más débiles del flujo de Simpro se apuntalan en el medio. Todo el intercambio se correlaciona solo en memoria durante los pocos segundos que dura el protocolo de enlace, por lo que este modo debe ejecutarse como una instancia única: no lo pongas detrás de un balanceador de carga.

Compilarlo tú mismo

Si estás trabajando en el código en lugar de solo usarlo:

npm install
npm run build        # compile
npm test             # run the unit tests
npm run login        # one-time browser sign-in (authorization_code); caches the refresh token
npm run build:mcpb   # produce the simpro-mcp-server.mcpb install file
npm start            # run it locally

npm run login ejecuta el dist/login.js compilado, así que compila primero; necesita que SIMPRO_CLIENT_ID y SIMPRO_CLIENT_SECRET estén definidas (consulta Ejecútalo localmente desde el código fuente más arriba).

Hay una suite de pruebas unitarias (npm test) que cubre las partes puras y deterministas: clasificación de búsqueda, formato de salida, rutas de las líneas de detalle y las utilidades de criptografía/almacenamiento de la autenticación. No hay ningún linter, y nada simula la red, así que comprobar a fondo un cambio sigue implicando compilarlo y probarlo contra una cuenta real de Simpro. Las notas de arquitectura y las peculiaridades de la API de Simpro que merece la pena conocer están en CLAUDE.md.