Zendesk Mcp

zendesk-mcp

一个 Model Context Protocol 服务，可向 Claude Code 和其他 MCP 客户端提供 Zendesk 工单的读取与写入工具。

功能

• 搜索、列出（支持分页）和获取 Zendesk 工单、评论及附件
• 创建工单并更新现有工单字段（包括群组、自定义状态和标签）
• 发布公开回复和内部备注
• 设置工单状态并将工单分配给 Agent
• 浏览并应用视图和宏
• 查找用户、群组、组织和自定义状态
• 读取和写入时间跟踪条目
• 将工单格式化为 Markdown 问题草稿，以便移交给跟踪系统（GitLab、GitHub、Jira）
• 提供两个 MCP 提示词（analyze-ticket、draft-ticket-response），用于分析工单和起草回复
• （可选）将 Zendesk 帮助中心文章公开为 MCP 资源
• （可选）通过 Git-Zen Zendesk 应用读取关联的 GitLab 问题／MR／提交

前提条件

• Python 3.10 或更高版本
• Zendesk OAuth 客户端。Zendesk 管理员可在此处创建： https://<your-subdomain>.zendesk.com/admin/apps-integrations/apis/zendesk-api/oauth_clients 将重定向 URL 设置为 http://localhost:8787/callback，并申请 read write 权限范围。

安装

安装到项目本地的虚拟环境中。使用 venv 可将 zendesk-mcp 及其依赖项与系统 Python 和其他项目隔离开来，也是下文所有操作的推荐方式。

从克隆的此仓库开始：

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

用于开发（也会安装 pytest）：

.venv/bin/pip install -e ".[dev]"

本 README 中的命令通过 .venv/bin/... 使用 venv 中的二进制文件。你也可以在每个 shell 中执行一次 source .venv/bin/activate，然后省略前缀，效果相同。

OAuth 设置

使用 venv 中的 Python 运行交互式设置：

.venv/bin/python -m zendesk_mcp setup

系统会提示你输入：

1. Zendesk 子域名（例如，acme.zendesk.com 的子域名为 acme）
2. 管理员创建的 OAuth 客户端 ID
3. OAuth 客户端密钥
4. （可选）Git-Zen 集成字段 ID — 请参阅可选：Git-Zen 集成
5. （可选）是否启用帮助中心知识库资源 — 请参阅可选：帮助中心知识库

设置程序会打开浏览器以进行 OAuth 授权，然后将令牌写入 ~/.config/zendesk-mcp/config.json（模式 0600）。

如果没有浏览器，URL 会显示在终端中 — 在任意设备上打开该 URL，点击 Allow，然后将生成的重定向 URL 粘贴回提示中。

令牌过期与刷新

Zendesk 访问令牌会过期。2026-04-30 当天或之后创建的 OAuth 客户端默认令牌有效期为 30 分钟；较早创建的客户端则会签发不过期的令牌，除非指定有效期。设置程序会请求有效期为 24 小时的访问令牌和有效期为 90 天的刷新令牌，以确保两种情况的行为一致；服务会自动续期访问令牌 — 在令牌过期前续期，并在 Zendesk 于请求过程中拒绝令牌时再次续期。

为实现这一点，配置文件还会在访问令牌旁存储 refresh_token、expires_at、client_id 和 client_secret。请将文件权限保持为 0600；该文件的信任级别与访问令牌本身相同。如果 OAuth 客户端未返回刷新令牌，设置程序会告知你，并直接使用该令牌。

在以下情况重新运行 .venv/bin/python -m zendesk_mcp setup：

• 刷新令牌过期（90 天未使用），或
• 你在 Zendesk 中撤销了 OAuth 授权。

在这两种情况下，工具都会返回 Zendesk authorization failed: ... Re-run: zendesk-mcp setup，而不会静默失败。

在 Claude Code 中注册

使用 venv 的 Python 绝对路径注册 MCP 服务。Claude Code 会在一个全新的 shell 中启动服务，该 shell 不会继承已激活的 venv，因此必须使用绝对路径——在这里仅指定 python 会导致无法导入 zendesk_mcp。

ZENDESK_MCP_DIR="$(pwd)"   # run this from the repo root, after install
claude mcp add --scope user zendesk -- "$ZENDESK_MCP_DIR/.venv/bin/python" -m zendesk_mcp

或者直接内联指定所需的绝对路径：

claude mcp add --scope user zendesk -- /absolute/path/to/zendesk-mcp/.venv/bin/python -m zendesk_mcp

然后将读取工具添加到 ~/.claude/settings.json 中的 permissions.allow，以避免每次调用都出现提示：

{
  "permissions": {
    "allow": [
      "mcp__zendesk__zendesk_get_ticket",
      "mcp__zendesk__zendesk_get_tickets",
      "mcp__zendesk__zendesk_get_comments",
      "mcp__zendesk__zendesk_list_attachments",
      "mcp__zendesk__zendesk_download_attachment",
      "mcp__zendesk__zendesk_search_tickets",
      "mcp__zendesk__zendesk_ticket_to_gitlab_context",
      "mcp__zendesk__zendesk_list_views",
      "mcp__zendesk__zendesk_get_view",
      "mcp__zendesk__zendesk_get_view_tickets",
      "mcp__zendesk__zendesk_list_macros",
      "mcp__zendesk__zendesk_preview_macro",
      "mcp__zendesk__zendesk_search_users",
      "mcp__zendesk__zendesk_get_groups",
      "mcp__zendesk__zendesk_get_group_users",
      "mcp__zendesk__zendesk_get_organization",
      "mcp__zendesk__zendesk_list_custom_statuses"
    ]
  }
}

写入工具（zendesk_post_comment、zendesk_post_internal_note、zendesk_set_ticket_status、zendesk_assign_ticket、zendesk_create_ticket、zendesk_update_ticket、zendesk_log_time、zendesk_add_tag、zendesk_remove_tag、zendesk_apply_macro）不会被加入默认允许列表，这是有意为之——Claude 每次调用时都会向你发出提示。

限制工具

默认情况下，每个工具都已启用。若要缩小部署的操作范围，例如工单文本由客户编写，且 Agent 不应回复客户，可以在 ~/.config/zendesk-mcp/config.json 中或在服务的环境中设置以下任一项。两处的值会合并。

配置键	环境变量	效果
"read_only": true	ZENDESK_MCP_READ_ONLY=true	不注册任何写入工具（评论、备注、状态、分配、创建/更新、标签、宏、时间记录）
"disabled_tools": ["zendesk_post_comment"]	ZENDESK_MCP_DISABLED_TOOLS=zendesk_post_comment,zendesk_apply_macro	不注册指定的工具

已禁用的工具永远不会被注册，因此模型无法看到或调用它。与任何工具都不匹配的名称会报告到 stderr。

工具

工单

返回工单记录的工具包含 channel，即工单到达的渠道（Zendesk 的 via.channel：web、email、api 等）；如果 Zendesk 未提供，则为 null。zendesk_get_ticket 还会以 {id, value} 对列表的形式返回 custom_fields；工单中未设置的字段，其值为 null。

工具	功能
zendesk_search_tickets	按状态、优先级、类型、受理人、请求者、标签或关键词搜索工单。每条结果都包含 channel
zendesk_get_tickets	分页并排序列出工单（page、per_page、sort_by、sort_order）。每条工单都包含 channel
zendesk_get_ticket	获取一条工单的元数据，包括 channel 和 custom_fields
zendesk_create_ticket	创建新工单（subject、description，以及可选的 priority/type/assignee_id/requester_id/tags/custom_fields）
zendesk_update_ticket	更新现有工单的一个或多个字段（status、priority、subject、type、assignee_id、requester_id、group_id、custom_status_id、tags、custom_fields、due_at）
zendesk_get_comments	获取工单的对话记录
zendesk_list_attachments	列出工单上的附件
zendesk_download_attachment	将附件下载到本地缓存目录。URL 必须属于你的 Zendesk 主机，且 dest_dir 必须位于缓存目录内，或位于配置中 attachment_allowed_dest_dirs 所列的目录中
zendesk_ticket_to_gitlab_context	将工单及其对话格式化为 Markdown issue 草稿
zendesk_post_comment	在工单上发布公开回复
zendesk_post_internal_note	在工单上发布仅 Agent 可见的内部备注
zendesk_set_ticket_status	设置工单状态（new、open、pending、hold、solved、closed）
zendesk_assign_ticket	通过电子邮件地址或 me 将工单分配给 Agent

标签

工具	功能
zendesk_add_tag	为工单添加标签（幂等）
zendesk_remove_tag	从工单移除标签（幂等）

视图和宏

工具	功能
zendesk_list_views	列出所有启用的视图
zendesk_get_view	获取视图的筛选条件和执行设置
zendesk_get_view_tickets	获取当前符合视图条件的工单。每张工单都包含 channel
zendesk_list_macros	列出启用的宏及其操作
zendesk_preview_macro	预览宏将进行的更改
zendesk_apply_macro	将宏应用到工单（应用字段更改并发布任何评论）

用户、群组和组织

工具	功能
zendesk_search_users	按姓名或电子邮件查找用户
zendesk_get_groups	列出所有启用的群组
zendesk_get_group_users	列出群组成员
zendesk_get_organization	获取组织信息，包括自定义字段
zendesk_list_custom_statuses	列出所有自定义工单状态及其 ID

时间跟踪

工具	功能
zendesk_get_time_tracking	读取工单的时间跟踪条目
zendesk_log_time	为工单记录时间条目

Git-Zen 集成

工具	功能
zendesk_get_git_zen_links	（仅限 Git-Zen）获取工单关联的 GitLab issue / MR / commit

提示词

该服务会公开两个 MCP 提示词，部分客户端（例如 Claude Desktop）会将其显示为斜杠命令：

提示词	参数	功能
analyze-ticket	ticket_id	要求模型获取工单，并生成摘要、状态/时间线以及关键互动要点
draft-ticket-response	ticket_id	要求模型获取工单并起草面向客户的回复（发布前需确认）

可选：Git-Zen 集成

如果你的 Zendesk 实例使用 Git-Zen 应用，zendesk_get_git_zen_links 工具可以读取其自定义字段载荷。在 Admin → Tickets → Fields 中找到实例的 Git-Zen 自定义字段 ID（这是一个数字 ID），然后在运行 .venv/bin/python -m zendesk_mcp setup 时设置，或编辑 ~/.config/zendesk-mcp/config.json 并添加：

{
  "git_zen_field_id": 12345678901234
}

如果未配置，zendesk_get_git_zen_links 会返回“未配置”消息。

可选：Help Center 知识库

如果你的 Zendesk 实例有已发布的 Help Center，你可以将其章节和文章作为 zendesk://knowledge-base MCP 资源公开。该资源会返回一个涵盖所有章节和文章的 JSON 文档，并缓存一小时。

此功能需选择启用。运行 .venv/bin/python -m zendesk_mcp setup 时对提示回答“y”，或将以下内容添加到 ~/.config/zendesk-mcp/config.json，即可启用：

{
  "knowledge_base_enabled": true
}

如果未设置该标志或其值为 false，则不会注册此资源，以便没有 Help Center 的实例保持资源列表为空。

可选：将附件下载到缓存目录之外

默认情况下，zendesk_download_attachment 会将文件写入 ~/.cache/zendesk-mcp/attachments/<ticket_id>/（可通过 attachment_cache_dir 配置）。dest_dir 参数可以将下载目标重定向到其他位置，但由于附件内容由工单撰写者控制，该工具仅接受位于缓存目录内或你明确允许的目录内的 dest_dir。将你想允许的目录添加到 ~/.config/zendesk-mcp/config.json：

{
  "attachment_allowed_dest_dirs": ["/home/me/work/support_bundles"]
}

检查前会解析路径，因此 .. 路径段和符号链接都无法逃出允许的目录。任何不在允许范围内的 dest_dir 都会在下载开始前被拒绝。

下载 URL 本身必须是配置的子域名对应的 <subdomain>.zendesk.com 上的 https URL；该工具会拒绝其他 URL，确保 OAuth 令牌不会发送到其他主机。归档文件最多包含 10,000 个条目，解压后最大为 256 MiB；tar 中非普通文件或目录的成员会被跳过。

开发

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

CI 使用 Python 3.10、3.11 和 3.12 运行测试（参见 .github/workflows/test.yml）。

发布

更新 pyproject.toml、mcpb/pyproject.toml（版本号和 zendesk-mcp== 固定版本）、mcpb/manifest.json 和 server.json（两个字段）中的版本，然后推送一个 v* 标签。这将触发 .github/workflows/release.yml，该工作流会发布到 PyPI、打包 MCPB 捆绑包、将 server.json 发布到 MCP Registry，并创建 GitHub release。

打标签前请确认版本号一致，否则发布会立即失败：

python3 .github/scripts/check_versions.py 0.1.5

许可证

Apache-2.0