Twenty MCP

ClaudeをTwenty CRMワークスペースに接続するリモートMCP（Model Context Protocol）サーバーです。Cloudflare Workers上にデプロイされ、OAuthを使用してチームでワンクリックでインストールできます。

機能

あらゆるTwentyオブジェクト（人、会社、商談、またはカスタムオブジェクト）で動作する、8つの汎用的なスキーマ駆動型ツールを提供します。MCPは実行時にTwentyのメタデータAPIをイントロスペクト（自己診断）するため、フィールドやオブジェクトを追加してもMCPを更新する必要はありません。

ツール

• list_objects, describe_object — CRM内の情報を探索

• find_records, get_record — フィルタ/並び替え/ページネーションを使用したクエリ

• create_record, update_record, delete_record — ミューテーション（書き込みモードで接続されている場合のみ）

• run_graphql — 生のメタデータ/GraphQL用のエスケープハッチ

• get_primer — 組織固有のドメインコンテキストとライブスキーマスナップショット

リソース（セッション開始時にClaudeによって自動読み込み）

• twenty://primer — コンパクトなスキーマスナップショットと統合された組織コンテキスト

• twenty://api/info — コネクタのステータスと現在のスコープ

インストール（チームメンバー向け、ワンクリック）

1. Claude → 設定 → コネクタ → カスタムコネクタを追加

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

3. Claudeが同意ページにリダイレクトします。個人用のTwenty APIキー（Twenty → 設定 → 開発者 → APIキーを生成）を貼り付けます。

4. 権限（読み取り専用または読み取り+書き込み）と、オプションでオブジェクトスコープを選択します。

5. 完了です。キーは暗号化されてCloudflare KVに保存され、セッションに紐付けられます。

Twentyで行った変更は、共有サービスアカウントではなく、あなたのTwentyユーザーに帰属します。

デプロイ（管理者向け、初回のみ）

1. 上記のデプロイボタンをクリックします。Cloudflareがリポジトリをフォークし、シークレットの入力を求めます。

2. 必要なシークレットを設定します：

   • COOKIE_ENCRYPTION_KEY — openssl rand -hex 32

   • TWENTY_BASE_URL — TwentyインスタンスのURL（例: https://crm.example.com）

3. （オプション）ADMIN_TOKENを設定します — openssl rand -hex 32 — プライマー管理用の /admin/* エンドポイントを有効にします。

4. デプロイされたURL（例: https://twenty-mcp.your-subdomain.workers.dev）を控えます。

5. <url>/mcp をチームと共有します。

Claude管理チームの場合：Claudeチーム管理コンソールで <url>/mcp を一度登録すると、すべてのチームメンバーのコネクタリストに表示されます。各メンバーは、自分のTwenty APIキーを貼り付けるための1回限りの同意ページを完了する必要があります。

プライマーのカスタマイズ

twenty://primer リソースは、ツールを呼び出す前にClaudeに対してCRMに関するコンテキストを提供します。これには2つの部分が含まれます：

1. 組織コンテキスト — ドメインモデル、カスタムオブジェクト、ビジネスルール、慣習を記述したMarkdownドキュメント。イントロスペクションでは取得できない情報（例：「オブジェクトAとオブジェクトBは独立しており、一方から他方を推論しないこと」など）。

2. スキーマスナップショット — TwentyのメタデータAPIから自動生成され、1時間キャッシュされます。

デフォルトでは、パート(1)は汎用的なTwentyテンプレートになっています。組織固有のコンテキストをアップロードするには：

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

コンテキストのMarkdownには、組織の活動内容、各カスタムオブジェクトの意味と関連性、階層化/分類モデル、命名規則、およびAIに対する「すべきこと/すべきでないこと」のルールを記述してください。テンプレート構造については src/primer/default-context.md を参照してください。

ローカル開発

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

ローカルのClaude Desktopを開発用ワーカーに接続するには、コネクタとして http://localhost:8787/mcp を追加してください。

認証の仕組み

TwentyにはアップストリームのOAuthプロバイダーがないため、認証はワークスペースごとのAPIキーで行われます。そのため：

• ワーカーは（Claudeコネクタで必要な）独自のOAuth 2.1エンドポイントを実行します。

• OAuth同意ステップ中に、ユーザーはHTMLフォームにTwenty APIキーを貼り付けます。

• ワーカーはTwentyの /metadata エンドポイントに対してキーを検証し、{twentyApiKey, mode, allowedObjects, label} を暗号化されたOAuthプロパティとして保存します。

• その後のすべてのMCPツール呼び出しでは、this.props を通じてユーザーのキーが利用可能になります。

つまり、このMCPは外側（Claudeに対して）はOAuth、内側（Twentyに対して）はAPIキーとして機能します。

スコーピング

各接続はインストール時に制限できます：

• モード: 読み取り専用にすると create_record / update_record / delete_record が非表示になります。

• 許可されたオブジェクト: カンマ区切りのリストで、特定のオブジェクトのみに制限できます。

オブジェクトレベルの権限も、ユーザーのAPIキーに付与されたロールを通じてTwenty自体によって強制されます（二重の安全策）。

アーキテクチャ

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)

ライセンス

Apache-2.0。fathom-mcp と同じアーキテクチャに基づいています。