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 eine Ein-Klick-Team-Installation bereitgestellt wird.

Funktionsweise

Stellt 8 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/Pagination

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

• run_graphql – Hintertür 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

Installation (Teammitglied, Ein-Klick)

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. Fügen Sie Ihren persönlichen Twenty-API-Schlüssel ein (unter Twenty → Einstellungen → Entwickler → API-Schlüssel generieren).

4. 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)

1. Klicken Sie auf den obigen Deploy-Button. Cloudflare wird das Repo forken und nach Secrets fragen.

2. Legen Sie die erforderlichen Secrets fest:

   • COOKIE_ENCRYPTION_KEY – openssl rand -hex 32

   • TWENTY_BASE_URL – Ihre Twenty-Instanz-URL (z. B. https://crm.example.com)

3. (Optional) Setzen Sie ADMIN_TOKEN – openssl rand -hex 32 – aktiviert die /admin/*-Endpunkte für die Primer-Verwaltung.

4. Notieren Sie die bereitgestellte URL, z. B. https://twenty-mcp.your-subdomain.workers.dev.

5. Teilen Sie <url>/mcp mit dem Team.

Für verwaltete Claude-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.

Anpassen des Primers

Die Ressource twenty://primer gibt Claude Kontext über Ihr CRM vor jedem Tool-Aufruf. Sie besteht aus zwei Teilen:

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 aus der Metadaten-API von Twenty generiert, für 1 Stunde zwischengespeichert.

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

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

Das Kontext-Markdown sollte beschreiben: Was Ihre Organisation tut, was jedes benutzerdefinierte Objekt bedeutet und wie sie zusammenhängen, Tiering-/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
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-Connectors).

• 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 nach außen hin OAuth (für Claude) und nach innen hin API-Schlüssel (für Twenty).

Scoping

Jede Verbindung kann bei der Installation eingeschränkt werden:

• Modus: schreibgeschützt verbirgt create_record / update_record / delete_record.

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

Berechtigungen auf Objektebene werden ebenfalls von Twenty selbst über die dem API-Schlüssel des Benutzers zugewiesene Rolle durchgesetzt – doppelt hält besser.

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. Basiert auf derselben Architektur wie fathom-mcp.