Twenty MCP

ClaudeをTwenty CRMワークスペースに接続するリモートMCP（Model Context Protocol）サーバーです。Cloudflare Workers上にデプロイされ、OAuthによるワンクリックでのチーム導入が可能です。

機能

あらゆるTwentyオブジェクト（人、会社、商談、またはカスタムオブジェクト）で動作する、9つの汎用的なスキーマ駆動型ツールを提供します。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 — コネクタのステータスと現在のスコープ

Related MCP server: twentycrm-graphql-mcp

インストール（チームメンバー向け）

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

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

3. Claudeが同意ページにリダイレクトします。そこで個人用のTwenty APIキーが必要になります。取得方法は以下の通りです：

   • ブラウザでTwentyワークスペースにログイン

   • 歯車アイコン（左下）をクリック → 設定

   • 開発者（サイドバーの「ワークスペース」セクション内）へ移動

   • + APIキーを作成をクリックし、名前（例: "Claude MCP"）を付けてキーをコピー

4. 同意フォームにAPIキーを貼り付けます。権限（読み取り専用または読み取り+書き込み）と、必要に応じてオブジェクトスコープを選択します。

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

Twentyで行った変更は、共有サービスアカウントではなく、あなたのTwentyユーザーによる操作として記録されます。

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

前提条件

• Cloudflareアカウント（無料プランで動作可能）

• Node.js 18以上

• 実行中のTwenty CRMインスタンス（セルフホストまたはクラウド）

手順

# 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

WorkerのURLは https://hia-twenty-mcp.<your-subdomain>.workers.dev となります。<url>/mcp をチームと共有してください。

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

オプション: 管理者トークンの設定

組織固有のプライマーコンテキストをアップロードするための /admin/* エンドポイントを有効にします（プライマーのカスタマイズを参照）：

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

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

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

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

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

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

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

コンテキストのマークダウンには、組織の業務内容、各カスタムオブジェクトの意味と関連性、分類モデル、命名規則、および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

# Make sure you have wrangler.local.jsonc set up (see Deploy section)
npm run dev            # wrangler dev on http://localhost:8787
npm run typecheck

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

認証の仕組み

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

• Workerは（Claudeコネクタで要求される）独自のOAuth 2.1エンドポイントを実行します。

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

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

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

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

スコーピング

各接続はインストール時に制限を設けることができます：

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

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

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

Twentyのバージョン互換性

Twenty v0.40+ でテスト済みです。このMCPは以下を使用します：

• REST API (/rest/<objects>)：レコードのCRUD用（深さは0または1に制限）

• GraphQLメタデータAPI (/metadata)：スキーマイントロスペクション用（リレーション情報にはField型の settings フィールドを使用）

• 複合フィールド（例: name.firstName, emails.primaryEmail）は、フィルタ内でドット表記にする必要があります

大幅に古いTwentyバージョンを使用している場合、メタデータクエリの形式が異なる可能性があります。エラーが発生した場合はIssueを作成してください。

アーキテクチャ

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