zendesk-mcp-server

Zendesk MCP 服务

一个 Model Context Protocol（MCP）服务，可将 Zendesk 接入你的 AI 助手，服务于对话双方。

面向客服人员：在帮助中心查找答案；起草、更新和翻译文章，同时保持各语言版本同步；端到端处理支持工单，包括评论、分流和图片附件。

面向客户：提供与帮助中心“提交请求”表单相同的入口。客户选择请求类型，按表单实际提出的问题逐步作答，附上屏幕截图，然后跟进工单——阅读回复、回复对方，并在问题解决后关闭工单。请参阅终端用户模式。

整个过程都可以用自然语言完成，无需切换应用。

它大致实现了 Zendesk agent for Microsoft 365 Copilot 的功能，但不局限于某一家供应商：它可接入任何 MCP 客户端（Claude Desktop、Claude Code、Cursor、VS Code 等）。而且，它始终使用每位用户自己的 Zendesk 权限进行操作，绝不使用共享的管理员密钥。

助手可以做什么

用自然语言提问；助手会判断上下文和意图，然后代表你调用合适的工具。

• 在帮助中心查找答案。“如何申请软件许可证？”或“休假政策是什么？”这类问题会找到相关的文章，匹配依据是含义而非关键词。
• 无需离开对话即可创建、查看和更新工单：创建工单、查看状态、添加公开回复或内部备注、更改优先级或受理人，以及将工单标记为已解决。
• 为报告或快速决策总结工单。助手会提取详细信息和完整的评论串，并用一句话概括要点。
• 阅读工单附带的屏幕截图和照片。错误对话框、界面截图和产品照片会以图像形式交给助手自己的模型，以便它进行描述或据此采取行动。
• 用自然语言搜索和分流你的工单队列：“显示我本周关于账单的未结工单。”
• 起草和维护知识库文章。你可以撰写新文章，也可以一次修订大型文章中的一个章节，避免将整个 HTML 正文来回传递给模型。
• 以客户而非客服人员的身份提交和跟进请求。选择供应商提供的请求类型，只回答表单提出的问题，然后跟踪请求：对方回复了什么、你回复了什么，以及请求是否已完成。

为什么选择此服务

大多数 Zendesk 集成都使用共享的管理员 API 密钥，让每位用户都能完全访问所有工单，并附带一组固定的工具。此服务采用了不同的设计。

• 按用户进行身份验证，仅支持 OAuth。两种传输方式都使用 OAuth 2.1 PKCE：每位用户使用自己的 Zendesk 凭据登录，因此助手只能查看和操作该用户有权访问的内容，与直接登录 Zendesk 时的权限范围相同。我们有意不支持静态 API 令牌（原因）。
• 一个服务面向两类用户。身份验证按用户进行，而非使用共享管理员密钥，因此同一安装既可服务于客服人员，也可服务于客户——终端用户界面是一个可启用的命名空间，使用 Zendesk 为请求者保留的 API 路径。大多数 Zendesk MCP 服务在设计上仅面向客服人员。
• 基于章节编辑文章。对于较长的帮助中心文章，可一次读取并改写一个章节（按 h1/h2/h3 标题解析），而不是让助手处理整篇 HTML 正文。针对性编辑可将令牌用量减少 10 到 100 倍。
• 原生多模态附件。工单图片会以原生 MCP 图片内容的形式返回，因此客户端自己的模型（Claude、GPT、Gemini 等）可以直接查看图像。不需要服务端视觉模型或额外的 API 密钥，也不会受限于某个提供商。非图片附件会以文本引用的形式返回，两种图片上限均可配置。
• 可按需精简的工具界面。可将每项操作作为独立工具公开，将它们分组成命名空间代理，或合并为一个统一工具。还可以按命名空间或只读操作进行筛选，让每个上下文只加载所需的工具界面（参见工具界面）。
• 两种部署方式，同一套身份验证机制。可在笔记本电脑上将其作为 stdio MCP 服务运行，也可将其部署为通过 HTTP 访问的私有远程 MCP 服务，每个请求使用独立的 Zendesk 会话，并由每个客户端携带其用户自己的令牌。
• 精简的技术栈：官方 MCP TypeScript SDK（@modelcontextprotocol/server）和 zod，用于访问 Zendesk Support 和 Help Center（Guide）API。

以下情况请考虑其他方案：

• 需要使用 Support 和 Guide 以外的 Zendesk 产品（Talk、Explore 分析、Sell）。此服务不涵盖这些端点。
• 需要单一共享服务帐户或静态 API 令牌身份验证。此服务出于设计考虑，两者均不支持（见下文）。

此服务不做什么

此服务不支持 API 令牌身份验证。它仅使用 OAuth 2.1 PKCE：任何传输方式都不支持 ZENDESK_EMAIL + ZENDESK_API_TOKEN（Basic 身份验证）模式。这是有意为之，原因有二。

1. API 令牌的安全性不足。 Zendesk API 令牌是长期有效的静态共享密钥，拥有签发者的全部权限。它无法按用户限定权限、不会短期过期，也不支持按用户授权或撤销。OAuth 2.1 PKCE 则会签发按用户区分且可撤销的令牌。
2. API 令牌无法扩展。 单个静态凭据无法将操作归属到具体用户，也无法按用户单独撤销。它还会使多用户远程部署变得不安全：通过 HTTP 使用时，每位调用者都能获得签发者的权限。

如果你确实需要 API 令牌或服务帐户模式（例如，使用共享帐户进行无头 CI），请使用其他支持此模式的 Zendesk MCP 服务。你可以在灵感与相关项目下找到一些项目。

快速开始：本地（stdio）

默认使用方式：一名开发者、一个 Zendesk 帐户，通过浏览器使用 OAuth 2.1 PKCE。你需要 Node.js >= 22 和一个 Zendesk 实例（Support 或 Suite）。

安装

# Run without installing
npx -y @fruggr/zendesk-mcp-server <your-subdomain>

# Or install globally
npm install -g @fruggr/zendesk-mcp-server
zendesk-mcp-server <your-subdomain>

登录需要 Zendesk OAuth 客户端，因此请先注册一个（见下一节）。

Zendesk OAuth 设置

1. 前往 Admin Center → Apps and integrations → APIs → OAuth Clients
2. 创建一个公共客户端：
   • Identifier：<your-subdomain>_zendesk（或设置 ZENDESK_OAUTH_CLIENT_ID）
   • Redirect URL：http://localhost:27439/callback（如果覆盖此端口，请将其改为与 OAUTH_CALLBACK_PORT / --callback-port 相匹配；Zendesk 接受多个重定向 URL，每行一个）

如果客户端限制了允许的作用域，则需要 read；除非服务以 --read-only 运行，否则还需要 write。该选项只会向 Zendesk 请求 read 作用域。

首次调用工具时，服务会启动登录流程：它会打开浏览器窗口，并在工具消息中返回授权 URL。调用不会阻塞等待登录，因此请在浏览器中完成身份验证，然后重试请求。令牌会保存到仅所有者可访问的文件中，并在重启后继续使用，因此 MCP 客户端重新启动服务时，你无需每次都重新进行身份验证（路径和覆盖选项：OAUTH_TOKEN_FILE）。多个实例可以并行运行，例如一个读写实例和一个 --read-only 实例，且无需交换凭据。

MCP 客户端配置

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "@fruggr/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"]
    }
  }
}

claude mcp add zendesk -- npx -y @fruggr/zendesk-mcp-server <your-subdomain> --mode single

{
  "servers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "@fruggr/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"]
    }
  }
}

遇到问题？请参阅故障排除。

快速开始：远程（HTTP）

实验性功能。 HTTP 传输已提供，但尚未在所有 MCP 客户端中针对真实 Zendesk 租户完成端到端测试。本地 stdio 是受支持的方式。

你也可以为一个 Zendesk 账户部署私有远程 MCP 服务。 它是独立的 OAuth 授权服务器：claude.ai 和 ChatGPT 等 Web 客户端可通过 URL 添加该服务并自行注册；每位用户通过它登录 Zendesk， 无需共享管理员密钥，也无需针对每个客户端单独配置 Zendesk。每个版本还会提供经过 强化的 distroless 容器镜像（ghcr.io/fruggr/zendesk-mcp-server），并经过签名和证明。完整指南涵盖镜像、需要添加到 Zendesk OAuth 客户端的唯一重定向 URL、 主密钥和授权存储、反向代理后的 --public-url、受信任客户端、MCP 客户端配置、CORS，以及仍由运营方负责的事项： docs/http-deployment.md。

工具概览

工具分为以下命名空间：工单、帮助中心、用户与组织、搜索、连接器偏好设置（此 MCP 服务自身的用户设置，例如 SLA 提醒阈值，不会写入 Zendesk），以及请求（面向最终用户的功能，可选择启用，详见最终用户模式）。服务会以以下三种模式之一注册这些工具，你可以在功能粒度和上下文预算之间进行权衡：

• all：每项操作都是独立工具，适合工具选择能力较强的客户端；
• namespace（默认）：每个命名空间对应一个代理工具，兼顾两者；
• single：所有操作都由单个 zendesk 工具提供，适合工具槽位有限的模型（连接器自身的偏好设置仍会通过旁边的 connector_preferences 代理工具提供）。

代理工具接收 { "operation": "<tool_name>", "params": { … } }，并根据原始架构验证 params。--namespace、--tool 和 --read-only 会在创建代理工具之前筛选工具，因此每个代理工具仅描述筛选后保留的操作。

选择工具清单只有一种方式（--namespace / --tool），--mode 决定如何打包，--read-only 则进一步缩小范围。如果这些选项的组合不够直观，请不要猜测——无需凭据，使用 --print-tools 即可让服务列出它会公开的工具。

每个工具及其描述和 read/write 模式见： docs/mcp-tools-reference.md。标志和实际示例见：docs/configuration.md。

最终用户模式

以上内容面向 Zendesk 客服人员。本节则介绍另一类用户：你的客户。

在网页上，客户通过帮助中心的“提交请求”表单创建工单——选择请求类型、填写相应字段、附加文件，之后再回来查看回复。最终用户模式让他们能在自己的助手中完成同样的流程。

适用对象

适用于引导客户使用 MCP 服务的供应商，让客户能够在他们已有的工作环境中获得支持。客户自行安装，并使用自己的帮助中心账户登录，且只能看到属于自己的内容。

启用方法

面向最终用户的工具位于 requests 命名空间中，且需要选择启用：客服人员的安装不应继承为其他用户设计的工具；其中一个工具（将请求标记为已解决）完全无法使用客服人员令牌——Zendesk 会接受请求，但不执行任何操作。建议同时提供 help_center，因为能够搜索知识库的客户往往无需创建工单。

相关标志以及如何让服务列出不同配置组合会公开的内容，详见：docs/configuration.md。

支持的流程

• 查看有哪些请求类型。 查看供应商提供的表单及其面向客户的名称。
• 了解表单需要填写哪些内容。 查看表单中的问题、必填项，以及下拉菜单中的确切选项，这样助手就能在对话中收集这些信息，而不是猜测请求参数。
• 提交请求，并附加文件。
• 跟进请求。 列出自己的请求，查看包含完整对话记录的单条请求（注明每条回复的发送者，并标明客服人员），回复，以及在请求解决后将其标记为已解决。

Zendesk 账户的要求

除客服人员模式已有的要求外，还需要一项条件：至少有一个标记为对最终用户可见的工单表单，因为客户需要从中选择。登录过程按设计必须通过浏览器交互完成——没有通过脚本或无头方式获取最终用户令牌的途径。这一保护机制同样能防止其他人冒充你的客户登录。

完整的前置条件见：docs/configuration.md。面向不使用终端的用户的分步指南见：docs/end-user-onboarding.md。

客户无法做什么——也不应该做什么

客户能做的比 Agent 少。这是设计如此，并非功能缺失：

• 只能处理自己的工单。 由 Zendesk 强制执行，而非我们。
• 不能添加内部备注，无论是哪个方向。仅 Agent 可见的备注永远不会出现在此界面返回的内容中——Zendesk 会在请求者查看工单时将其完全过滤掉。
• 不能设置优先级或类型。 客户设置这两项时，Zendesk 都会将其丢弃；分流仍由 Agent 负责。
• 只有 Agent 接手工单后，才能关闭工单。 在此之前，Zendesk 不会允许请求者解决工单，因此工具会如实说明，而不会假装可以操作。
• 不能搜索所有工单，不能查找用户，也不能访问视图或宏。

帮助中心上下文

除了工具之外，服务端还会向大模型提供你的帮助中心结构：已启用的区域设置、带 ID 的类别 → 分区树、可见性细分和权限组。有了这些信息，它就能使用真实 ID，而不是猜测或模糊匹配名称。所有内容都通过 MCP 原生渠道传递，即在 initialize 时发送的 instructions 数据块，以及用于获取拓扑信息和读取（或固定）单篇文章的只读资源。资源使用调用者自己的令牌获取，不支持资源的客户端会静默忽略它们。

公开的内容、预先列出推荐文章会产生多少请求，以及如何分别关闭各项功能：docs/help-center-context.md。

配置

CLI 标志（--mode、--namespace、--read-only、--transport、--public-url 等）和环境变量（ZENDESK_SUBDOMAIN、OAUTH_TOKEN_FILE、PUBLIC_URL、附件视觉处理上限）的完整参考，请参阅 docs/configuration.md。每个变量都有自己的锚点，因此你可以直接链接到特定设置。

故障排查

OAuth 登录期间浏览器未打开、回调端口已被占用、每次都必须重新进行身份验证，以及 Guide 管理端点上的 Permission denied，详见 docs/troubleshooting.md。使用 LOG_LEVEL=debug 重启，可查看完整的 OAuth 流程跟踪信息。

开发

仓库设置、工具链、开发模式以及如何测试 PR 分支，详见 CONTRIBUTING.md。架构和代码风格规范见 AGENTS.md。

常见问题

支持哪些 Zendesk 产品？ Zendesk Support（工单、用户、组织）和 Help Center / Guide（文章、分区、类别、翻译、标签、内容标签、细分、附件）。Talk、Explore 和 Sell 不在支持范围内。

我需要 Zendesk 管理员 API 密钥吗？ 不需要，而且服务端不支持使用此类密钥。每位用户都使用自己的凭据进行身份验证，服务端严格按照其权限执行操作 （原因）。

通过 npx 运行安全吗？ 发布版本通过 CI 使用 npm Trusted Publishing（OIDC）发布，因此每个版本都带有构建来源证明，可在其 npm 页面上验证。服务端绝不会记录任何机密信息。

贡献

欢迎提交拉取请求，也包括 AI 辅助完成的请求，但作者必须亲自阅读并验证每一行内容。贡献指南、作者检查清单和审查工作流见 CONTRIBUTING.md。

版本遵循 SemVer 规范，并根据 Conventional Commits 自动发布；版本历史见 CHANGELOG.md。

灵感与相关项目

本项目的开发参考了：

• 官方 Zendesk API 文档
• mattcoatsworth/zendesk-mcp-server
• koundinya/zd-mcp-server

许可证

MIT

由 Digital4better 为 Fruggr 项目构建并维护。