upstream-twenty/packages/twenty-docs/l/zh/user-guide/ai/capabilities/mcp.mdx

---
title: MCP服务器
description: 使用 Model Context Protocol 将 AI 助手连接到你的 Twenty 工作区。
---

Twenty 提供一个 [MCP](https://modelcontextprotocol.io/) 服务器，使 AI 助手——Claude Desktop、Claude Code、Cursor、ChatGPT 等——能够通过自然语言读取和写入您的 CRM 数据。

将您的**工作区 URL**（用于访问 Twenty 的 URL）用作 MCP 端点。 在 Twenty Cloud 上，您的工作区 URL 可能是 `https://{mycompany}.twenty.com`，也可能是自定义域名。 服务器可通过以下地址访问：

| 环境      | MCP 端点                                                                     |
| ------- | -------------------------------------------------------------------------- |
| **云端**  | `https://{your-workspace-url}/mcp` (例如 `https://mycompany.twenty.com/mcp`) |
| **自托管** | `https://{your-domain}/mcp`                                                |

## 身份验证方法

您可以通过两种方式对 MCP 客户端进行身份验证：**OAuth**（推荐）或 **API 密钥**。

### 选项 A — OAuth（推荐）

使用 OAuth 时，您的 MCP 客户端会打开浏览器窗口供您登录。 不会在配置文件中存储任何机密，令牌会自动刷新。

<Note>
OAuth 需要支持[MCP 授权规范](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization)的 MCP 客户端。 Claude Desktop、Claude Code、Cursor 和 ChatGPT 均支持它。
</Note>

将以下内容添加到 MCP 客户端配置中，并将 `{your-workspace-url}` 替换为您的工作区主机（例如 `mycompany.twenty.com`）：

```json
{
  "mcpServers": {
    "twenty": {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp"
    }
  }
}
```

就这样——无需 API 密钥。 客户端首次连接时将：

1. 通过 `/.well-known/oauth-protected-resource` 和 `/.well-known/oauth-authorization-server` 发现 Twenty 的 OAuth 元数据
2. 通过动态客户端注册（RFC 7591）将自身注册为 OAuth 客户端
3. 打开您的浏览器以授权访问
4. 接收令牌并连接到 MCP 服务器

后续连接会重用已存储的令牌并自动刷新。

### 选项 B — API 密钥

如果您的 MCP 客户端不支持 OAuth，或您更喜欢静态凭据，请在 `Authorization` 请求头中传递 API 密钥：

```json
{
  "mcpServers": {
    "twenty": {
      "type": "streamable-http",
      "url": "https://{your-workspace-url}/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

<Warning>
您的 API 密钥可访问工作区数据。 请不要将其纳入版本控制，也不要放入共享的 dotfiles。
</Warning>

要创建 API 密钥，请前往 **Settings → MCP & APIs → API → + Create key**。 详见[API](/l/zh/developers/extend/api#create-an-api-key)。

## 快速开始

### 1. 复制配置

在 Twenty 中前往 **Settings → MCP & APIs → MCP**。 选择您的身份验证方式（OAuth 或 API 密钥），复制 JSON 片段（其中已包含您的工作区 URL），并将其粘贴到 MCP 客户端的配置文件中。

| 客户端                | 配置文件位置                                                                                                                              |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |
| **Claude Code**    | `~/.claude.json` (用户) 或 `.mcp.json` (项目)                                                                                            |
| **Cursor**         | 在您的项目中为 `.cursor/mcp.json`，或全局为 `~/.cursor/mcp.json`                                                                                |
| **ChatGPT**        | 在 **Settings → Apps & Connectors → Advanced settings** 中开启开发者模式，然后在 **Settings → Apps & Connectors** 中使用 **Create** 添加 MCP 服务器      |

### 2. 连接

重启您的 MCP 客户端（或重新加载配置）。 如果使用 OAuth，您将被重定向到 Twenty 以授权访问。 如果使用 API 密钥，连接会立即建立。

### 3. 开始使用

让您的 AI 助手与您的 CRM 交互：

* *"给我展示最近创建的 5 家公司"*
* *"在 Acme Corp 新建一位名为 Jane Doe 的联系人"*
* *"查找所有价值超过 $10k 的未关闭商机"*

## 可用工具

连接后，MCP 服务器会提供与 Twenty API 一一对应的工具。 推荐的工作流程是：

1. **`learn_tools`** — 获取特定工具的输入模式
2. **`execute_tool`** — 运行工具

您无需记住工具名称。 询问您的 AI 助手它能做什么，它会自动调用 `learn_tools`。

## 权限

MCP 连接将继承已通过身份验证的用户（OAuth）的权限，或继承分配给 API 密钥的角色。 要限制 MCP 服务器的操作范围：

* **OAuth**：生效的是该用户在工作区中的角色。
* **API 密钥**：在 **Settings → Members → Roles** 下为该 API 密钥分配角色。 参见[权限](/l/zh/user-guide/permissions-access/capabilities/permissions)。

## 自托管配置

对于自托管实例，请将 `{your-workspace-url}` 替换为您的服务器 URL。 请确保您环境中的 `SERVER_URL` 与 Twenty 实例的公共 URL 一致——该值用于生成 OAuth 发现元数据。

```bash
SERVER_URL=https://twenty.yourcompany.com
```

MCP 端点、OAuth 端点以及发现元数据都基于该值生成。

## 故障排除

**"Unauthorized" 或 401 错误**

* OAuth：清除 MCP 客户端中存储的令牌并重新连接以重新授权。
* API 密钥：验证该密钥有效且未过期。 如有需要，请重新生成。

**OAuth 流程未打开浏览器**

* 确保您的 MCP 客户端支持 MCP 授权。 如果不支持，请改用 API 密钥方法。

**连接超时**

* 确认从您的机器可以访问 MCP 端点 URL。 对于自托管实例，请检查服务器是否正在运行，并确认 `SERVER_URL` 设置正确。