Twenty MCP

Ein Remote-MCP-Server (Model Context Protocol), der Claude mit einem Twenty CRM-Workspace verbindet und auf Cloudflare Workers mit OAuth für die Ein-Klick-Installation im Team bereitgestellt wird.

Funktionsweise

Stellt 9 generische, schema-gesteuerte Tools bereit, die mit jedem Twenty-Objekt (Person, Unternehmen, Opportunity oder benutzerdefinierte Objekte) funktionieren. Das MCP untersucht die Metadaten-API von Twenty zur Laufzeit – Sie müssen das MCP nie aktualisieren, wenn Sie Felder oder Objekte hinzufügen.

Tools

• list_objects, describe_object – entdecken, was im CRM vorhanden ist

• find_records, get_record – Abfragen mit Filter/Sortierung/Paginierung

• create_record, update_record, delete_record – Mutationen (nur bei Verbindung im Schreibmodus)

• run_graphql – Notausgang für rohe Metadaten/GraphQL

• get_primer – organisationsspezifischer Domänenkontext + Live-Schema-Snapshot

Ressourcen (werden beim Start der Sitzung automatisch von Claude geladen)

• twenty://primer – Organisationskontext zusammengeführt mit einem kompakten Schema-Snapshot

• twenty://api/info – Connector-Status und aktuelle Scopes

Related MCP server: twentycrm-graphql-mcp

Installation (Teammitglied)

1. In Claude → Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen

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

3. Claude leitet Sie zu einer Zustimmungsseite weiter, auf der Sie Ihren persönlichen Twenty-API-Schlüssel benötigen. So erhalten Sie einen:

   • Melden Sie sich in Ihrem Twenty-Workspace im Browser an

   • Klicken Sie auf das Zahnrad-Symbol (unten links) → Einstellungen

   • Gehen Sie zu Entwickler (unter dem Abschnitt Workspace in der Seitenleiste)

   • Klicken Sie auf + API-Schlüssel erstellen, geben Sie ihm einen Namen (z. B. "Claude MCP") und kopieren Sie den Schlüssel

4. Fügen Sie den API-Schlüssel in das Zustimmungsformular ein. Wählen Sie die Berechtigung (schreibgeschützt oder Lesen+Schreiben) und optionale Objekt-Scopes.

5. Fertig. Ihr Schlüssel wird verschlüsselt in Cloudflare KV gespeichert und an Ihre Sitzung gebunden.

Änderungen, die Sie in Twenty vornehmen, werden Ihrem Twenty-Benutzer zugeordnet, nicht einem gemeinsamen Dienstkonto.

Bereitstellung (Admin, erstmalig)

Voraussetzungen

• Ein Cloudflare-Konto (kostenloser Plan reicht aus)

• Node.js 18+

• Eine laufende Twenty CRM-Instanz (selbst gehostet oder Cloud)

Schritte

# 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

Ihre Worker-URL lautet https://hia-twenty-mcp.<your-subdomain>.workers.dev. Teilen Sie <url>/mcp mit dem Team.

Für von Claude verwaltete Teams: Registrieren Sie <url>/mcp einmal in der Claude-Team-Admin-Konsole – es erscheint dann in der Connector-Liste jedes Teammitglieds. Jedes Mitglied muss dennoch die einmalige Zustimmungsseite ausfüllen, um seinen eigenen Twenty-API-Schlüssel einzufügen.

Optional: Admin-Token festlegen

Aktiviert die /admin/*-Endpunkte zum Hochladen von organisationsspezifischem Primer-Kontext (siehe Anpassen des Primers):

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

Anpassen des Primers

Die Ressource twenty://primer gibt Claude Kontext über Ihr CRM, bevor Tool-Aufrufe getätigt werden. Sie enthält zwei Teile:

1. Organisationskontext – ein Markdown-Dokument, das Ihr Domänenmodell, benutzerdefinierte Objekte, Geschäftsregeln und Konventionen beschreibt. Dinge, die die Introspektion nicht erfassen kann (z. B. "Objekt A und Objekt B sind unabhängig – leiten Sie nicht eines vom anderen ab").

2. Schema-Snapshot – automatisch generiert aus der Metadaten-API von Twenty, zwischengespeichert für 1 Stunde.

Standardmäßig ist Teil (1) eine generische Twenty-Vorlage. Um Ihren organisationsspezifischen Kontext hochzuladen:

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

Das Kontext-Markdown sollte beschreiben: was Ihre Organisation tut, was jedes benutzerdefinierte Objekt bedeutet und wie sie zusammenhängen, Klassifizierungsmodelle, Namenskonventionen und alle "Tu dies / tu das nicht"-Regeln für die KI. Siehe src/primer/default-context.md für die Vorlagenstruktur.

Lokale Entwicklung

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

Um einen lokalen Claude Desktop mit dem Entwicklungs-Worker zu verbinden, fügen Sie http://localhost:8787/mcp als Connector hinzu.

Funktionsweise der Authentifizierung

Twenty hat keinen vorgelagerten OAuth-Anbieter – die Authentifizierung erfolgt über API-Schlüssel pro Workspace. Daher:

• Der Worker betreibt seinen eigenen OAuth 2.1-Endpunkt (erforderlich für Claude-Connectoren).

• Während des OAuth-Zustimmungsschritts fügt der Benutzer seinen Twenty-API-Schlüssel in ein HTML-Formular ein.

• Der Worker validiert den Schlüssel gegen den /metadata-Endpunkt von Twenty und speichert dann {twentyApiKey, mode, allowedObjects, label} als verschlüsselte OAuth-Eigenschaften.

• Jeder nachfolgende MCP-Tool-Aufruf hat den Schlüssel des Benutzers über this.props verfügbar.

Das bedeutet, das MCP ist außen OAuth (für Claude) und innen API-Schlüssel (für Twenty).

Scoping

Jede Verbindung kann bei der Installation eingeschränkt werden:

• Modus: schreibgeschützt blendet create_record / update_record / delete_record aus.

• Erlaubte Objekte: durch Kommas getrennte Liste, um auf bestimmte Objekte zu beschränken.

Objekt-Ebene-Berechtigungen werden auch von Twenty selbst über die Rolle erzwungen, die mit dem API-Schlüssel des Benutzers verknüpft ist – doppelt hält besser.

Twenty-Versionskompatibilität

Getestet mit Twenty v0.40+. Das MCP verwendet:

• REST API (/rest/<objects>) für Datensatz-CRUD – Tiefe auf 0 oder 1 begrenzt

• GraphQL-Metadaten-API (/metadata) für Schema-Introspektion – verwendet das settings-Feld im Feldtyp für Beziehungsinformationen

• Zusammengesetzte Felder (z. B. name.firstName, emails.primaryEmail) müssen in Filtern mit Punktnotation angegeben werden

Wenn Sie eine deutlich ältere Twenty-Version verwenden, kann die Form der Metadatenabfrage abweichen. Eröffnen Sie ein Issue, wenn Sie auf Fehler stoßen.

Architektur

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)

Lizenz

Apache-2.0