Zendesk

@mindstone/mcp-server-zendesk

Zendesk Support MCP 服务——通过标准 stdio MCP 包处理工单、用户、评论、宏、账户设置和支持工作流发现。

最适合希望助手通过本地 MCP 主机对 Zendesk 工单进行分类、总结和更新的支持团队。

状态

• 版本： 0.4.1 · npm
• 身份验证： 混合模式（API 令牌或 OAuth）（ZENDESK_CLIENT_SECRET）
• 工具： 26（工单、用户、评论、宏、视图、帮助中心、满意度）
• 接入方式： 云 API
• 机器可读： STATUS.json

为什么开发此项目

Zendesk 已宣布推出自己的 MCP 客户端和服务体验，以实现更广泛的平台集成。此软件包面向希望安装并直接运行本地 Zendesk Support 连接器的 MCP 主机。

它可以帮助助手完成用户通常会让人工处理的支持工作：查找紧急工单、获取最新上下文、起草或添加评论、应用宏、查询用户和组织，以及检查支持设置。这样可以更快地进行工单分类和跟进，同时将客户撰写的工单文本视为需要引用和总结的内容，而不是需要遵循的指令。

交互示例

“查找优先级高的未结 Zendesk 工单，并显示第一条工单的最新详情。”

主机调用的工具：

1. search_zendesk_tickets — 搜索 type:ticket status:open priority:high 并返回工单摘要。
2. get_zendesk_ticket — 获取选中的工单，包括经过封装的主题和描述文本。

响应（节选）：

{
  "ok": true,
  "ticket": {
    "id": 12345,
    "status": "open",
    "priority": "high",
    "subject": "<untrusted-content source=\"external-ticket\">Login issue</untrusted-content>",
    "description": "<untrusted-content source=\"external-ticket\">Customer cannot access the admin dashboard.</untrusted-content>"
  }
}

要求

• Node.js 20+
• npm

一键安装

点击按钮后，主机将提示你填写：ZENDESK_CONFIG_PATH、ZENDESK_CLIENT_SECRET。

{
  "mcpServers": {
    "Zendesk": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-zendesk"
      ],
      "env": {
        "ZENDESK_CONFIG_PATH": "~/.mcp/zendesk",
        "ZENDESK_CLIENT_SECRET": ""
      }
    }
  }
}

快速开始

安装和构建

cd <path-to-repo>/connectors/zendesk
npm install
npm run build

npx（发布后）

npx -y @mindstone/mcp-server-zendesk

本地

node dist/index.js

配置

环境变量

• ZENDESK_CONFIG_PATH — 配置目录的路径，其中包含 accounts.json 和 credentials/
• ZENDESK_CLIENT_ID — OAuth 客户端 ID，用于续期令牌文件中未包含自身 client_id 的登录；在刷新令牌时读取
• ZENDESK_CLIENT_SECRET — 仅用于机密 OAuth 客户端，且仅与 ZENDESK_CLIENT_ID 一同发送；公共（PKCE）客户端不需要此项
• MCP_HOST_BRIDGE_STATE — 可选的主机桥接状态文件路径，用于凭据管理
• MINDSTONE_REBEL_BRIDGE_STATE — MCP_HOST_BRIDGE_STATE 的向后兼容别名

身份验证

每个账户使用两种凭据之一。对于给定的子域名，OAuth 登录优先于 API 令牌。

OAuth 登录（首选）。 主机应用执行 Zendesk 登录（例如，使用 PKCE 的授权码流程），并将结果以仅所有者可读写的权限（0600）写入 ZENDESK_CONFIG_PATH 下的 credentials/<subdomain>.token.json：

{
  "access_token": "…",
  "refresh_token": "…",
  "expires_in": 1800,
  "expires_at": 1767225600000,
  "token_type": "bearer",
  "subdomain": "acme",
  "email": "[email protected]",
  "client_id": "your-oauth-client-id",
  "scope": "read write"
}

expires_at 是以毫秒为单位的时间戳。client_id 和 scope 为可选项；如果存在，刷新时会使用该客户端，并请求相同的作用域。

连接器会自行续期访问令牌：在令牌到期前五分钟内，或收到 401 响应后续期：

• 它会向 https://<subdomain>.zendesk.com/oauth/tokens 发送 JSON 请求，其中包含刷新令牌和客户端 ID（令牌文件中的 client_id，否则使用 ZENDESK_CLIENT_ID）。公共客户端不需要客户端密钥。
• 并发工具调用会共用一次刷新操作，并会先重新读取令牌文件，因此会使用其他进程续期后的令牌，而不是再次消耗刷新令牌。
• 轮换后的刷新令牌会通过原子替换文件的方式保存，且仅当文件中仍是刚刚消耗的刷新令牌时才会保存。若刷新期间令牌文件被删除（账户已断开连接），则不会重新创建该文件；若文件已被新的登录信息替换，则会保留并使用新文件。
• 如果无法保存续期后的令牌（磁盘已满或为只读），连接器会继续在内存中使用该令牌，且不会再次发送已消耗的刷新令牌；在文件发生变化前，list_zendesk_accounts 会在该账户上显示 warning。重启后，账户可能需要重新登录。
• 如果 Zendesk 拒绝刷新令牌（invalid_grant、invalid_client、unauthorized_client），或者没有客户端 ID，工具调用会失败并返回 AUTH_FAILED 和“Reconnect Zendesk…”，而 list_zendesk_accounts 会报告 reconnect-required。令牌文件会保留；重新登录会替换该文件。
• 临时故障（服务器错误、速率限制、网络问题）会在访问令牌过期后返回 AUTH_REFRESH_FAILED（“try again in a moment”）；下次调用时会重试。

API 令牌。 在 accounts.json（见下文）中包含 subdomain、email 和 apiToken 的条目，会作为 HTTP Basic 身份验证发送。API 令牌不会过期，因此始终处于 active 状态。

独立配置目录

要使用 API 令牌，请创建配置目录和 accounts.json 文件：

mkdir -p ~/.mcp/zendesk
cat > ~/.mcp/zendesk/accounts.json <<'EOF'
{
  "accounts": [
    {
      "subdomain": "yourcompany",
      "email": "[email protected]",
      "apiToken": "your-zendesk-api-token"
    }
  ],
  "defaultSubdomain": "yourcompany"
}
EOF

主机配置示例

Claude Desktop / Cursor

{
  "mcpServers": {
    "Zendesk": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-zendesk"],
      "env": {
        "ZENDESK_CONFIG_PATH": "~/.mcp/zendesk"
      }
    }
  }
}

本地开发（无需发布到 npm）

{
  "mcpServers": {
    "Zendesk": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/zendesk/dist/index.js"],
      "env": {
        "ZENDESK_CONFIG_PATH": "~/.mcp/zendesk"
      }
    }
  }
}

Mindstone Rebel

"Zendesk": {
  "name": "Zendesk",
  "type": "stdio",
  "command": "node",
  "args": ["<path-to-repo>/connectors/zendesk/dist/index.js"],
  "env": {
    "ZENDESK_CONFIG_PATH": "~/Library/Application Support/mindstone-rebel/mcp/zendesk",
    "MCP_HOST_BRIDGE_STATE": "~/Library/Application Support/mindstone-rebel/mcp/rebel-inbox-bridge.json"
  },
  "description": "Zendesk support tickets...",
  "catalogId": "bundled-zendesk"
}

工具（26）

账户管理

• list_zendesk_accounts — 列出已连接账户及其身份验证状态
• remove_zendesk_account — 断开 Zendesk 账户
• authenticate_zendesk_account — 使用 API 令牌连接

工单

• search_zendesk_tickets — 使用 Zendesk 查询语法搜索（最多 1000 条结果）
• export_zendesk_tickets — 使用游标导出，不受 1000 条结果的限制
• get_zendesk_ticket — 按 ID 获取单个工单
• get_zendesk_tickets_by_ids — 批量获取多个工单
• create_zendesk_ticket — 创建新工单
• update_zendesk_ticket — 更新工单字段、状态或添加评论

用户

• search_zendesk_users — 按姓名、电子邮件或查询搜索
• get_zendesk_user — 按 ID 获取用户
• create_or_update_zendesk_user — 创建用户，或更新具有相同电子邮件的用户

评论

• list_zendesk_ticket_comments — 列出对话线程并解析作者
• add_zendesk_ticket_comment — 添加公开回复或内部备注

发现

• list_zendesk_groups — 列出客服组
• list_zendesk_ticket_fields — 列出工单字段，包括自定义字段
• list_zendesk_views — 列出已保存的工单视图
• list_zendesk_view_tickets — 执行视图并列出其中的工单
• list_zendesk_organizations — 列出组织
• get_zendesk_organization — 根据 ID 获取单个组织

宏

• list_zendesk_macros — 列出或搜索宏
• get_zendesk_macro — 获取宏详情
• apply_zendesk_macro — 预览宏并将其应用到工单

帮助中心

• search_zendesk_help_center_articles — 搜索知识库文章
• get_zendesk_help_center_article — 阅读完整的帮助中心文章

满意度

• list_zendesk_satisfaction_ratings — 根据评分／日期筛选条件列出 CSAT 评分

安全注意事项

• Zendesk API 令牌凭据存放在 accounts.json 中；OAuth 凭据从 ZENDESK_CONFIG_PATH 下的 credentials/*.token.json 读取。续期后的令牌会写入同一文件夹中权限为 0600 的临时文件，然后重命名到目标位置；刷新失败时不会删除令牌文件。
• 绝不会记录访问令牌、刷新令牌和令牌端点的错误描述；只记录 HTTP 状态和 OAuth 错误代码。
• 配置了主机桥接时，桥接调用会使用 MCP_HOST_BRIDGE_STATE 中的令牌发送到 127.0.0.1。
• 工单主题、描述、评论正文、用户／组织／客服组／宏／视图／字段文本以及其他由外部编写的字符串，在提供给模型前，都会使用 <untrusted-content source="...">...</untrusted-content> 封装，并对闭合标签进行转义。
• 写入文件的工单导出操作仅限于系统临时目录（通过符号链接安全的规范路径包含性检查），并在新建的专用导出目录中创建文件，目录权限仅限所有者访问——只采用所请求的文件名，完整路径以 file_path 返回，且绝不会触碰已有文件。export_zendesk_tickets 和 get_zendesk_tickets_by_ids 被标注为非只读，因为它们可能写入本地导出文件。
• 在任何网络调用前，都会验证电子邮件输入的格式和电话号码输入的 E.164 格式；数字 ID 和分页参数必须为正整数。
• 账户移除、工单更新、工单评论和宏应用均已标记，以便支持此功能的主机在更改支持数据前进行确认。

冒烟测试

请 MCP 主机运行：

列出我未关闭的 Zendesk 工单

如果失败，请确认：

• dist/index.js 文件存在（运行 npm run build）
• ZENDESK_CONFIG_PATH 指向可读取的目录
• accounts.json 包含有效的子域名、电子邮件和 API 令牌

故障排除

许可

FSL-1.1-MIT — 功能源代码许可证 1.1 版，未来将采用 MIT 许可证。该软件将于 2030-04-08 转为 MIT 许可证。