内容
# Twenty CRM MCP 服务器
Twenty CRM 的 MCP（模型上下文协议）服务器，通过 14 种工具为 AI 代理提供对 CRM 数据的完全访问权限 - 搜索、创建、批量操作、全文本搜索、分析等。
与任何 MCP 客户端配合使用：Claude Code、Claude Desktop、Cursor、Shortwave、Cline 等。
## 为什么选择这个？
大多数 Twenty MCP 集成都是围绕 REST API 的薄封装。而本集成直接使用 Twenty 的 GraphQL API，这意味着：
- **高效的字段选择** - 仅获取需要的字段，而非整个记录
- **嵌套关系遍历** - 在单个查询中获取具有人员信息的公司
- **完整的过滤语法** - 完整的 Twenty GraphQL 过滤语言，而非简化的子集
- **批量操作** - 在一次调用中创建、更新或删除最多 100 条记录
- **模式自省** - 代理可以在运行时发现可用的字段
- **可点击的 URL** - 每个返回的记录都包含指向 Twenty UI 的直接链接
## 快速入门
您需要一个 Twenty CRM API 密钥。在 Twenty 中找到它，路径为 **设置 -> API 密钥**。
### Claude Code
```bash
claude mcp add crm-twenty \
-e TWENTY_CRM_URL=https://your-twenty-instance.com \
-e TWENTY_CRM_API_KEY=your-api-key \
-- npx -y github:onprem-ai/mcp-crm-twenty
```
### Claude Desktop / Cursor / 其他 MCP 客户端
将以下内容添加到您的 MCP 配置中：
```json
{
"crm-twenty": {
"command": "npx",
"args": ["-y", "github:onprem-ai/mcp-crm-twenty"],
"env": {
"TWENTY_CRM_URL": "https://your-twenty-instance.com",
"TWENTY_CRM_API_KEY": "your-api-key"
}
}
}
```
就这样 - 服务器在本地运行，并连接到您的 Twenty CRM 实例。
### 远程 / 共享设置（Shortwave，网页应用，团队）
将服务器部署为远程 HTTP 端点。团队成员使用他们自己的 Twenty API 密钥进行身份验证 - 不需要共享凭证。
**1. 启动服务器：**
```bash
TWENTY_CRM_URL=https://your-twenty-instance.com docker compose up -d
```
**2. 将您的 MCP 客户端连接到：**
```
https://your-server.com/mcp
```
连接时，您的客户端将打开一个页面，您可以在其中输入您的个人 Twenty CRM API 密钥。该密钥直接用于与 Twenty 进行身份验证 - 服务器不会存储它。
> 支持 MCP OAuth 的客户端（例如 Shortwave）会自动处理此过程。
> 支持自定义标头的客户端也可以直接将密钥作为 `Authorization: Bearer <your-api-key>` 传递。
**生产提示：** 将 `MCP_SERVER_URL` 设置为您的公共 URL，以便 OAuth 重定向正确工作：
```bash
TWENTY_CRM_URL=https://your-twenty-instance.com \
MCP_SERVER_URL=https://mcp.yourcompany.com \
docker compose up -d
```
## 工具
| 工具 | 描述 |
|------|-------------|
| `crm_twenty_search` | 搜索和列出记录，支持过滤、排序、分页 |
| `crm_twenty_fulltext_search` | 跨所有记录类型进行全文搜索 |
| `crm_twenty_get` | 按 ID 获取单个记录 |
| `crm_twenty_create` | 创建新记录（支持更新插入） |
| `crm_twenty_bulk_create` | 一次创建最多 100 条记录 |
| `crm_twenty_update` | 更新现有记录 |
| `crm_twenty_bulk_update` | 更新匹配过滤器的所有记录 |
| `crm_twenty_delete` | 软删除记录 |
| `crm_twenty_bulk_delete` | 软删除匹配过滤器的所有记录 |
| `crm_twenty_restore` | 恢复软删除的记录 |
| `crm_twenty_duplicates` | 检查重复人员或公司 |
| `crm_twenty_group_by` | 按字段聚合记录 |
| `crm_twenty_schema` | 发现任何资源的可用字段 |
所有工具均适用于：`people`、`companies`、`opportunities`、`tasks`、`notes`、`noteTargets`、`taskTargets`、`attachments`、`favorites`、`timelineActivities`、`workspaceMembers`。
## 使用示例
**搜索人员：**
```json
{"resource": "people", "filter": {"name": {"firstName": {"like": "%John%"}}}, "first": 10}
```
**获取具有联系人的公司：**
```json
{"resource": "companies", "id": "uuid", "fields": ["id", "name", "people { id name { firstName lastName } }"]}
```
**批量创建联系人：**
```json
{"resource": "people", "data": [{"name": {"firstName": "Jane", "lastName": "Doe"}, "emails": {"primaryEmail": "jane@example.com"}}], "upsert": true}
```
**按阶段聚合交易：**
```json
{"resource": "opportunities", "groupBy": [{"stage": true}]}
```
**全文搜索：**
```json
{"searchInput": "GPU server"}
```
## 过滤语法
过滤器使用 Twenty 的 GraphQL 过滤格式：
- 字符串：`{eq, neq, like, ilike, startsWith, endsWith, in, is}`
- 数字：`{eq, neq, gt, gte, lt, lte, in, is}`
- 布尔值：`{eq, is}`
- 日期时间：`{eq, neq, gt, gte, lt, lte, is}`
- 逻辑：`{and: [...], or: [...], not: {...}}`
## 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `TWENTY_CRM_URL` | 是 | - | 您的 Twenty CRM 实例 URL |
| `TWENTY_CRM_API_KEY` | 仅限标准输入 | - | API 密钥（HTTP 模式下不需要） |
| `MCP_TRANSPORT` | 否 | `stdio` | 设置为 `http` 以使用远程模式 |
| `MCP_SERVER_URL` | 否 | `http://0.0.0.0:3000` | 公共 URL（用于 OAuth 重定向） |
| `PORT` | 否 | `3000` | HTTP 端口 |
## 架构
使用具有类型化输入的 Twenty GraphQL API，以实现高效的字段选择。HTTP 模式包含一个内置的 OAuth 2.1 提供程序，以便 Shortwave 等客户端无需任何外部身份验证基础设施即可进行身份验证 - 用户只需在 OAuth 同意流程中输入其 Twenty API 密钥。
有关设计规格和实施计划，请参见 `docs/`。
