Twenty MCP

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

功能介绍

提供 9 个通用的、模式驱动的工具，适用于任何 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 — 连接器状态和当前作用域

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 密钥。

可选：设置管理员令牌

启用 /admin/* 端点以上传组织特定的入门上下文（参见 自定义入门指南）：

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

自定义入门指南

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

1. 组织上下文 — 一份 Markdown 文档，描述你的领域模型、自定义对象、业务规则和约定。内省无法捕获的内容（例如“对象 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>"

上下文 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

# 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 运行其自己的 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 密钥的角色强制执行——双重保险。

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