Twenty MCP

Un servidor MCP (Model Context Protocol) remoto que conecta Claude a un espacio de trabajo de Twenty CRM, desplegado en Cloudflare Workers con OAuth para una instalación de equipo con un solo clic.

Qué hace

Expone 8 herramientas genéricas basadas en esquemas que funcionan con cualquier objeto de Twenty (Persona, Empresa, Oportunidad o cualquier objeto personalizado). El MCP realiza una introspección de la API de metadatos de Twenty en tiempo de ejecución; nunca necesitas actualizar el MCP cuando añades campos u objetos.

Herramientas

• list_objects, describe_object — descubre qué hay en el CRM

• find_records, get_record — consulta con filtro/ordenación/paginación

• create_record, update_record, delete_record — mutaciones (solo cuando está conectado en modo escritura)

• run_graphql — vía de escape para metadatos/graphql sin procesar

• get_primer — contexto de dominio específico de la organización + instantánea del esquema en vivo

Recursos (cargados automáticamente por Claude al iniciar la sesión)

• twenty://primer — contexto de la organización fusionado con una instantánea compacta del esquema

• twenty://api/info — estado del conector y ámbitos actuales

Instalación (miembro del equipo, un solo clic)

1. En Claude → Ajustes → Conectores → Añadir conector personalizado

2. URL: https://<tu-worker>.workers.dev/mcp

3. Claude te redirige a una página de consentimiento. Pega tu clave de API personal de Twenty (desde Twenty → Ajustes → Desarrolladores → Generar clave de API).

4. Elige el permiso (solo lectura o lectura+escritura) y los ámbitos de objeto opcionales.

5. Listo. Tu clave se almacena cifrada en Cloudflare KV, vinculada a tu sesión.

Los cambios que realices en Twenty se atribuyen a tu usuario de Twenty, no a una cuenta de servicio compartida.

Despliegue (administrador, primera vez)

1. Haz clic en el botón de despliegue de arriba. Cloudflare bifurcará el repositorio y solicitará secretos.

2. Establece los secretos requeridos:

   • COOKIE_ENCRYPTION_KEY — openssl rand -hex 32

   • TWENTY_BASE_URL — la URL de tu instancia de Twenty (ej. https://crm.example.com)

3. (Opcional) Establece ADMIN_TOKEN — openssl rand -hex 32 — habilita los endpoints /admin/* para la gestión del primer.

4. Anota la URL desplegada, ej. https://twenty-mcp.tu-subdominio.workers.dev.

5. Comparte <url>/mcp con el equipo.

Para equipos gestionados por Claude: registra <url>/mcp una vez en la consola de administración del equipo de Claude; aparecerá en la lista de conectores de cada miembro del equipo. Cada miembro aún debe completar la página de consentimiento única para pegar su propia clave de API de Twenty.

Personalización del primer

El recurso twenty://primer proporciona a Claude contexto sobre tu CRM antes de cualquier llamada a herramientas. Contiene dos partes:

1. Contexto de la organización — un documento markdown que describe tu modelo de dominio, objetos personalizados, reglas de negocio y convenciones. Cosas que la introspección no puede capturar (ej. "El Objeto A y el Objeto B son independientes; no infieras uno del otro").

2. Instantánea del esquema — generada automáticamente a partir de la API de metadatos de Twenty, almacenada en caché durante 1 hora.

De forma predeterminada, la parte (1) es una plantilla genérica de Twenty. Para subir tu contexto específico de la organización:

# Set ADMIN_TOKEN first if you haven't:
# wrangler secret put ADMIN_TOKEN

# Upload your context markdown:
curl -X PUT https://<your-worker>.workers.dev/admin/primer \
  -H "Authorization: Bearer <your-admin-token>" \
  -H "Content-Type: text/markdown" \
  --data-binary @path/to/your-context.md

# Verify it's loaded:
curl https://<your-worker>.workers.dev/admin/primer \
  -H "Authorization: Bearer <your-admin-token>"

# Revert to the bundled default:
curl -X DELETE https://<your-worker>.workers.dev/admin/primer \
  -H "Authorization: Bearer <your-admin-token>"

El markdown de contexto debe describir: qué hace tu organización, qué significa cada objeto personalizado y cómo se relacionan, modelos de clasificación/niveles, convenciones de nomenclatura y cualquier regla de "haz esto / no hagas aquello" para la IA. Consulta src/primer/default-context.md para ver la estructura de la plantilla.

Desarrollo local

npm install
cp .dev.vars.example .dev.vars
# edit .dev.vars — set COOKIE_ENCRYPTION_KEY, TWENTY_BASE_URL, and optionally ADMIN_TOKEN
npm run dev            # wrangler dev on http://localhost:8787
npm run typecheck

Para conectar un Claude Desktop local al worker de desarrollo, añade http://localhost:8787/mcp como conector.

Cómo funciona la autenticación

Twenty no tiene un proveedor de OAuth ascendente; la autenticación es mediante claves de API por espacio de trabajo. Por lo tanto:

• El Worker ejecuta su propio endpoint OAuth 2.1 (requerido por los conectores de Claude).

• Durante el paso de consentimiento de OAuth, el usuario pega su clave de API de Twenty en un formulario HTML.

• El Worker valida la clave contra el endpoint /metadata de Twenty y luego almacena {twentyApiKey, mode, allowedObjects, label} como propiedades de OAuth cifradas.

• Cada llamada posterior a la herramienta MCP tiene la clave del usuario disponible a través de this.props.

Esto significa que el MCP es OAuth por fuera (para Claude) y clave de API por dentro (para Twenty).

Ámbitos

Cada conexión puede restringirse en el momento de la instalación:

• Modo: solo lectura oculta create_record / update_record / delete_record.

• Objetos permitidos: lista separada por comas para restringir a objetos específicos.

Los permisos a nivel de objeto también son aplicados por el propio Twenty a través del rol asignado a la clave de API del usuario: doble seguridad.

Arquitectura

Claude ↔ OAuth 2.1 ↔ Worker ↔ REST+GraphQL ↔ Twenty workspace
                        │
                        ├─ McpAgent Durable Object (per session)
                        ├─ OAUTH_KV (token store, schema cache, primer)
                        └─ twenty://primer (org context + live schema)

Licencia

Apache-2.0. Basado en la misma arquitectura que fathom-mcp.