内容
# 工 MCP
[模型上下文协议](https://modelcontextprotocol.io) 服务器，暴露了完整的 Gong.io 公共 API 接口（公共 API v2 + Engage API），适用于像 Claude Desktop、Claude Code、Cursor 以及其他任何与 MCP 兼容的主机。
每个 Gong 端点对应一个 MCP 工具，总共 58 个工具。
## 涵盖范围
| 类别 | 工具 |
|---|---|
| 通话 | list, create, get, add-media, extensive, transcript, manual-CRM-associations, AI content, users-access (get/grant/revoke) |
| 用户 | list, get, extensive, settings-history |
| 统计数据 | activity aggregate / aggregate-by-period / day-by-day / scorecards, interaction |
| CRM | integrations (list/register/delete), entities (get/upload), entity-schema (get/upload), request-status |
| 库 | folders, folder-content |
| 权限 | profiles (list/get/create/update), profile-users |
| 数据隐私 | email/phone lookup, email/phone erasure |
| 设置 | scorecards, trackers |
| 工作空间 | list |
| 会议（Beta） | create, update, delete, integration-status |
| 参与度（Beta） | content shared/viewed, custom action |
| 数字交互（Alpha） | post |
| 审计日志 | list |
| 辅导 | get |
| Engage 流 | list, folders, prospects (get/assign/unassign-by-crm-id/unassign-by-instance-id) |
## 工具参考
每个 Gong 端点都暴露为一个单独的 MCP 工具，名为 `gong_<area>_<action>`。标记为 **WRITE** 的工具会修改 Gong 中的状态 - 其余工具是只读的。
### 通话
| 工具 | 描述 |
|---|---|
| `gong_calls_list` | 列出某个日期范围内的通话；返回元数据，按光标分页。 |
| `gong_calls_create` | **WRITE** 注册在 Gong 之外录制的通话。 |
| `gong_calls_get` | 通过 ID 获取单个通话的基本元数据。 |
| `gong_calls_add_media` | **WRITE** 将音频/视频附加到先前创建的通话中。 |
| `gong_calls_extensive` | 详细的通话数据：参与方、内容、交互、跟踪器、主题、简报、亮点。 |
| `gong_calls_transcript` | 具有说话者 ID 和时间戳的逐句转录。 |
| `gong_calls_manual_crm_associations` | 列出手动与 CRM 对象关联的通话。 |
| `gong_calls_ai_content` | AI 生成的通话简报、关键点、行动项、摘要。 |
| `gong_calls_users_access_get` | 哪些用户有权访问一组通话。 |
| `gong_calls_users_access_grant` | **WRITE** 授予用户访问通话的权限。 |
| `gong_calls_users_access_revoke` | **WRITE** 撤销用户对通话的访问权限。 |
### 用户
| 工具 | 描述 |
|---|---|
| `gong_users_list` | 列出工作空间中的所有用户。 |
| `gong_users_get` | 通过 ID 获取单个用户。 |
| `gong_users_extensive` | 详细的 user 数据，包括管理器、自定义字段。 |
| `gong_users_settings_history` | 用户设置的历史变化。 |
### 统计数据
| 工具 | 描述 |
|---|---|
| `gong_stats_activity_aggregate` | 按用户聚合活动指标（通话、时间等）。 |
| `gong_stats_activity_aggregate_by_period` | 按周期聚合活动。 |
| `gong_stats_activity_day_by_day` | 每天的活动明细。 |
| `gong_stats_activity_scorecards` | 按用户的记分卡结果。 |
| `gong_stats_interaction` | 交互统计（讲话比例、最长的独白等）。 |
### CRM
| 工具 | 描述 |
|---|---|
| `gong_crm_integrations_list` | 列出已配置的 CRM 集成。 |
| `gong_crm_integrations_register` | **WRITE** 注册新的 CRM 集成。 |
| `gong_crm_integrations_delete` | **WRITE** 删除 CRM 集成。 |
| `gong_crm_entities_get` | 获取 CRM 实体记录。 |
| `gong_crm_entities_upload` | **WRITE** 将 CRM 实体记录上传到 Gong。 |
| `gong_crm_entity_schema_get` | 获取 CRM 实体类型的模式。 |
| `gong_crm_entity_schema_upload` | **WRITE** 上传 CRM 实体模式。 |
| `gong_crm_request_status` | 检查 CRM 上传请求的狀態。 |
### 库
| 工具 | 描述 |
|---|---|
| `gong_library_folders` | 列出库文件夹。 |
| `gong_library_folder_content` | 列出库文件夹中的通话。 |
### 权限
| 工具 | 描述 |
|---|---|
| `gong_permission_profiles_list` | 列出所有权限配置文件。 |
| `gong_permission_profile_get` | 获取单个权限配置文件。 |
| `gong_permission_profile_create` | **WRITE** 创建权限配置文件。 |
| `gong_permission_profile_update` | **WRITE** 更新权限配置文件。 |
| `gong_permission_profile_users` | 列出分配给配置文件的用户。 |
### 数据隐私
| 工具 | 描述 |
|---|---|
| `gong_data_privacy_email_lookup` | 查找与电子邮件关联的所有数据。 |
| `gong_data_privacy_phone_lookup` | 查找与电话号码关联的所有数据。 |
| `gong_data_privacy_erase_email` | **WRITE** 通过电子邮件进行 GDPR 删除。 |
| `gong_data_privacy_erase_phone` | **WRITE** 通过电话进行 GDPR 删除。 |
### 设置
| 工具 | 描述 |
|---|---|
| `gong_settings_scorecards` | 列出记分卡定义。 |
| `gong_settings_trackers` | 列出智能跟踪器定义。 |
### 工作空间
| 工具 | 描述 |
|---|---|
| `gong_workspaces_list` | 列出所有工作空间。 |
### 会议（Beta）
| 工具 | 描述 |
|---|---|
| `gong_meetings_create` | **WRITE** 创建 Gong 调度的会议。 |
| `gong_meetings_update` | **WRITE** 更新会议。 |
| `gong_meetings_delete` | **WRITE** 删除会议。 |
| `gong_meetings_integration_status` | 日历/会议集成状态。 |
### 参与度（Beta）
| 工具 | 描述 |
|---|---|
| `gong_engagement_content_shared` | **WRITE** 记录与潜在客户共享的内容。 |
| `gong_engagement_content_viewed` | **WRITE** 记录潜在客户查看的内容。 |
| `gong_engagement_action` | **WRITE** 记录自定义参与度操作。 |
### 数字交互（Alpha）
| 工具 | 描述 |
|---|---|
| `gong_digital_interaction_post` | **WRITE** 发布数字交互事件。 |
### 审计日志
| 工具 | 描述 |
|---|---|
| `gong_logs_list` | 列出审计日志条目。 |
### 辅导
| 工具 | 描述 |
|---|---|
| `gong_coaching_get` | 获取用户/期间的辅导统计数据。 |
### Engage 流
| 工具 | 描述 |
|---|---|
| `gong_flows_list` | 列出 Engage 流。 |
| `gong_flows_folders_list` | 列出 Engage 流文件夹。 |
| `gong_flows_prospects_get` | 列出流中的潜在客户。 |
| `gong_flows_prospects_assign` | **WRITE** 将潜在客户分配到流中。 |
| `gong_flows_prospects_unassign_by_crm_id` | **WRITE** 按 CRM ID 取消分配潜在客户。 |
| `gong_flows_prospects_unassign_by_instance_id` | **WRITE** 按流实例 ID 取消分配潜在客户。 |
## 先决条件
- **Node.js ≥ 18** (`node --version`)。
- 一个 **Gong 访问密钥 + 密钥**。在 Gong 中生成：**公司设置 → 生态系统 → API**。创建密钥的用户需要在工作空间上具有 API 权限。
## 1. 安装
```bash
git clone <此仓库> gong-mcp
cd gong-mcp
npm install
```
## 2. 配置凭证
复制示例 env 文件并填写您的密钥/密钥：
```bash
cp .env.example .env
# 然后编辑 .env
```
或在您的 shell 中导出变量：
```bash
export GONG_ACCESS_KEY="您的密钥"
export GONG_ACCESS_KEY_SECRET="您的密钥"
# 仅当您的 Gong 帐户位于 EU 节点时需要：
# export GONG_BASE_URL="https://api.eu.gong.io"
```
| 环境变量 | 必需 | 默认值 |
|---|---|---|
| `GONG_ACCESS_KEY` | 是 | — |
| `GONG_ACCESS_KEY_SECRET` | 是 | — |
| `GONG_BASE_URL` | 否 | `https://api.gong.io`（覆盖为 EU 节点的 `https://api.eu.gong.io`） |
## 3. 构建和运行
```bash
npm run build # 编译 TypeScript → dist/
node dist/index.js # 在标准输入/输出上启动 MCP 服务器
```
或在开发过程中直接从源代码运行（无构建步骤）：
```bash
npm run dev # 使用 tsx 直接运行 src/index.ts
```
服务器通过 **stdio** 讲话 MCP 协议 - 它在启动时保持沉默，等待 MCP 客户端连接。如果您看不到输出，这是正常的。如果您看到 `gong-mcp failed to start: ...`，则环境变量未正确设置。
### HTTP 模式（可流式 HTTP）
通过 `--port` 传递以通过 HTTP 而不是标准输入/输出提供 MCP 服务：
```bash
node dist/index.js --port 8765 # 绑定到 127.0.0.1:8765/mcp
node dist/index.js --port 8765 --host 0.0.0.0 # 绑定到所有接口
PORT=8765 node dist/index.js # PORT 环境变量也有效
```
端点是 `POST/GET/DELETE /mcp`，符合 [MCP 流式 HTTP 规范](https://modelcontextprotocol.io/specification)。服务器在所有会话中保持相同的 Gong 速率限制器（3 req/sec）。
一旦软件包发布，您就可以运行它而无需克隆：
```bash
GONG_ACCESS_KEY=... GONG_ACCESS_KEY_SECRET=... \
npx -y gong-mcp --port 8765
```
## 4. 从 MCP 客户端连接
您几乎从不直接运行 `gong-mcp` - 而是将 MCP 客户端指向它。以下是您选择的客户端：
### Claude Desktop
编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"gong": {
"command": "node",
"args": ["/绝对路径/to/gong-mcp/dist/index.js"],
"env": {
"GONG_ACCESS_KEY": "您的密钥",
"GONG_ACCESS_KEY_SECRET": "您的密钥"
}
}
}
}
```
重启 Claude Desktop。打开一个新的聊天窗口并询问“列出我的最近的 Gong 通话” - Claude 应该调用 `gong_calls_list`。
### Claude Code
```bash
claude mcp add gong \
-e GONG_ACCESS_KEY=您的密钥 \
-e GONG_ACCESS_KEY_SECRET=您的密钥 \
-- node /绝对路径/to/gong-mcp/dist/index.js
```
然后在 Claude Code 中输入 `/mcp` 以确认它已连接。
### Cursor
设置 → MCP → 添加一个新服务器，其 `command` / `args` / `env` 形状与上述 Claude Desktop 配置相同。
### 任意其他 MCP 主机
它是一个纯粹的标准输入/输出 MCP 服务器。任何遵循 MCP 规范的软件都有效：
```
command: node
args: ["/绝对路径/to/gong-mcp/dist/index.js"]
env: GONG_ACCESS_KEY, GONG_ACCESS_KEY_SECRET
```
## 烟雾测试（无需 MCP 客户端）
```bash
npm test
```
运行涵盖速率限制器、身份验证标头、配置验证和工具注册的单元测试。不会调用实时 Gong API。
要针对真实租户验证身份验证，最简单的单行命令是：
```bash
curl -u "$GONG_ACCESS_KEY:$GONG_ACCESS_KEY_SECRET" https://api.gong.io/v2/workspaces
```
200 + JSON 表示您的凭证有效。401 表示密钥/密钥错误；403 表示密钥缺少正确的范围。
## 故障排除
| 症状 | 可能原因 |
|---|---|
| 启动时出现 `Missing Gong credentials` | `GONG_ACCESS_KEY` / `GONG_ACCESS_KEY_SECRET` 未导出到进程中。在 Claude Desktop 中，在 `env` 键下设置它们 - `.env` 文件不会自动加载。 |
| 任意工具出现 `401 Unauthorized` | 错误的密钥/密钥，或密钥已轮换。 |
| 特定工具出现 `403 Forbidden` | 访问密钥缺少所需的范围（例如 `api:calls:read`）。在 Gong 的 API 设置中添加范围。 |
| 所有请求都慢 | 预期：Gong 每秒限制 3 个请求。客户端排队以保持在限制之下。 |
| 尽管有限流仍出现 `429` 错误 | 另一个进程正在共享相同的 API 密钥。服务器仅限流其自己的流量。 |
| EU 租户在每次调用时返回 404 | 设置 `GONG_BASE_URL=https://api.eu.gong.io`。 |
## 速率限制
Gong 强制执行每秒 3 个请求和每个访问密钥每天 10,000 个请求。客户端使用每秒 3 个请求的令牌桶，并在 `429` / `5xx` 响应时重试最多 3 次，同时遵守 `Retry-After`。
## 错误处理
在 Gong API 错误时，工具返回 `isError: true` 以及 JSON 有效载荷 `{ status, method, path, body, retryAfterSeconds }`，以便模型可以决定如何重试。
## 测试
```bash
npm test
```
涵盖：令牌桶限流、身份验证标头构造、配置验证、完整的工具集注册。
## 许可证
MIT
