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 en equipo con un solo clic.

Qué hace

Expone 9 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 filtros/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

Related MCP server: twentycrm-graphql-mcp

Instalación (miembro del equipo)

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 donde necesitarás tu clave de API personal de Twenty. Para obtener una:

   • Inicia sesión en tu espacio de trabajo de Twenty en el navegador

   • Haz clic en el icono de engranaje (abajo a la izquierda) → Ajustes

   • Ve a Desarrolladores (bajo la sección Espacio de trabajo en la barra lateral)

   • Haz clic en + Crear clave de API, dale un nombre (p. ej., "Claude MCP") y copia la clave

4. Pega la clave de API en el formulario de consentimiento. 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)

Requisitos previos

• Una cuenta de Cloudflare (el plan gratuito funciona)

• Node.js 18+

• Una instancia de Twenty CRM en ejecución (autoalojada o en la nube)

Pasos

# 1. Clone the repo
git clone https://github.com/High-Impact-Athletes/hia-twenty-mcp.git
cd hia-twenty-mcp
npm install

# 2. Create the KV namespace
npx wrangler kv namespace create twenty-mcp-oauth
# Note the ID from the output (e.g. "3cd89a10677c4d2ba32c9e59482afa23")

# 3. Create your local config (not committed to git)
cp wrangler.jsonc wrangler.local.jsonc
# Edit wrangler.local.jsonc:
#   - Set "account_id" to your Cloudflare account ID
#   - Replace <OAUTH_KV_ID> with the KV namespace ID from step 2

# 4. Set secrets
npx wrangler secret put COOKIE_ENCRYPTION_KEY --config wrangler.local.jsonc
# Paste the output of: openssl rand -hex 32
# This is just a random string for encrypting OAuth cookies — not a Twenty secret.

npx wrangler secret put TWENTY_BASE_URL --config wrangler.local.jsonc
# Paste your Twenty instance URL, e.g. https://crm.example.com
# This is whatever URL you use to log into Twenty in your browser.

# 5. Deploy
npm run deploy

La URL de tu Worker será https://hia-twenty-mcp.<tu-subdominio>.workers.dev. 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 debe completar la página de consentimiento única para pegar su propia clave de API de Twenty.

Opcional: establecer un token de administrador

Permite los puntos finales /admin/* para cargar el contexto del "primer" específico de la organización (ver Personalizar el primer):

npx wrangler secret put ADMIN_TOKEN --config wrangler.local.jsonc
# Paste the output of: openssl rand -hex 32

Personalizar el 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 (p. ej., "El Objeto A y el Objeto B son independientes; no infieras uno del otro").

2. Instantánea del esquema — generada automáticamente desde 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 cargar el contexto específico de tu organización:

# 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, 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

# Make sure you have wrangler.local.jsonc set up (see Deploy section)
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 se realiza mediante claves de API por espacio de trabajo. Por lo tanto:

• El Worker ejecuta su propio punto final 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 punto final /metadata de Twenty y luego almacena {twentyApiKey, mode, allowedObjects, label} como propiedades 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: seguridad reforzada.

Compatibilidad de versiones de Twenty

Probado con Twenty v0.40+. El MCP utiliza:

• API REST (/rest/<objetos>) para CRUD de registros — profundidad limitada a 0 o 1

• API de metadatos GraphQL (/metadata) para la introspección de esquemas — utiliza el campo settings en el tipo Field para información de relación

• Los campos compuestos (p. ej., name.firstName, emails.primaryEmail) deben estar notados con puntos en los filtros

Si utilizas una versión de Twenty significativamente anterior, la forma de la consulta de metadatos puede diferir. Abre una incidencia si encuentras errores.

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