Twenty MCP

一个远程 MCP（模型上下文协议）服务器，将 Claude 连接到 Twenty CRM 工作区，部署在 Cloudflare Workers 上，并支持 OAuth 以实现一键式团队安装。

功能介绍

提供 8 个通用的、模式驱动的工具，适用于任何 Twenty 对象（人员、公司、机会或任何自定义对象）。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 将 fork 该仓库并提示输入密钥。

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/* 端点以进行 primer 管理。

4. 记录部署的 URL，例如 https://twenty-mcp.your-subdomain.workers.dev。

5. 与团队共享 <url>/mcp。

对于 Claude 管理的团队：在 Claude 团队管理控制台中注册一次 <url>/mcp — 它将出现在每个团队成员的连接器列表中。每位成员仍需完成一次性授权页面以粘贴他们自己的 Twenty API 密钥。

自定义 primer

twenty://primer 资源在任何工具调用之前为 Claude 提供关于您 CRM 的上下文。它包含两部分：

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 连接到开发 worker，请添加 http://localhost:8787/mcp 作为连接器。

身份验证工作原理

Twenty 没有上游 OAuth 提供商 — 身份验证通过每个工作区的 API 密钥进行。因此：

• Worker 运行其自己的 OAuth 2.1 端点（Claude 连接器所需）。

• 在 OAuth 授权步骤中，用户将他们的 Twenty API 密钥粘贴到 HTML 表单中。

• Worker 根据 Twenty 的 /metadata 端点验证密钥，然后将 {twentyApiKey, mode, allowedObjects, label} 存储为加密的 OAuth 属性。

• 随后的每次 MCP 工具调用都可以通过 this.props 获取用户的密钥。

这意味着 MCP 在外部是 OAuth（针对 Claude），在内部是 API 密钥（针对 Twenty）。

作用域

每个连接都可以在安装时进行限制：

• 模式： 只读模式会隐藏 create_record / update_record / delete_record。

• 允许的对象： 以逗号分隔的列表，用于限制特定对象。

对象级权限也由 Twenty 本身通过附加到用户 API 密钥的角色强制执行 — 双重保险。

架构

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 相同的架构。