Zendesk MCP Server

Zendesk MCP 服务

适用于 Zendesk 的模型上下文协议服务。

此服务提供与 Zendesk 的全面集成。它提供：

• 用于检索和管理 Zendesk 工单及评论的工具
• 用于工单分析和起草回复的专用提示词
• 对 Zendesk 帮助中心文章知识库的完整访问权限

设置

• 构建：uv venv && uv pip install -e .，或简写为 uv build。
• 配置身份验证：参见下文的身份验证。
• 在 Claude 桌面应用中配置：

{
  "mcpServers": {
      "zendesk": {
          "command": "uv",
          "args": [
              "--directory",
              "/path/to/zendesk-mcp-server",
              "run",
              "zendesk"
          ]
      }
  }
}

身份验证

此服务使用 OAuth 进行身份验证。每位操作人员使用自己的 Zendesk 登录信息授权，因此 API 调用会携带其身份，Zendesk 会严格按照其在 UI 中应用的权限进行处理，包括角色、群组限制和工单访问权限。他们发布的评论也会以其本人名义发布。

API 令牌身份验证仍然可用，但已弃用。请参阅从 API 令牌迁移。

1. 注册公共 OAuth 客户端

在管理中心中，前往 Apps and integrations > APIs > OAuth clients 并创建客户端：

字段	值
客户端类型	Public — 此服务运行在每位操作人员的机器上，因此没有可保密的密钥。改用 PKCE。
重定向 URL	http://localhost:4567/callback
允许的范围	tickets:read tickets:write ticket_attachments:read users:read hc:read

设置 Allowed scopes 是可选的，但建议设置：即使代码发生变化，它也会限制此客户端的任何令牌可请求的权限范围。

记下客户端的 Identifier，这就是下文的 ZENDESK_CLIENT_ID。

如果 Zendesk 拒绝 http://localhost:4567/callback，请改为注册 https://localhost，并在第 3 步中使用 zendesk-auth --manual。

2. 配置环境

将 .env.example 复制为 .env，并设置：

ZENDESK_SUBDOMAIN=acme        # for https://acme.zendesk.com
ZENDESK_CLIENT_ID=your-client-identifier

请勿将 .env 纳入版本控制。

有两个可选设置，且都必须与 OAuth 客户端一致：

变量	默认值	何时更改
ZENDESK_OAUTH_REDIRECT_URI	http://localhost:4567/callback	端口 4567 已被占用，或客户端注册了不同的重定向 URL。必须与客户端上的某个重定向 URL 完全一致。
ZENDESK_TOKEN_FILE	$XDG_CONFIG_HOME/zendesk-mcp/tokens.json	要将令牌存储在其他位置时，例如 Docker 卷。

3. 授权此机器（仅需一次）

uv run zendesk-auth

这会打开浏览器，请求操作人员批准访问，并在本地存储生成的令牌。此后，服务会自行续期访问权限；除非令牌被撤销，或超过刷新令牌的有效期（此服务请求的期限为 90 天）未使用，否则操作人员无需再次执行此操作。

如果浏览器无法访问此机器（例如远程 Shell，或 OAuth 客户端注册了 https://localhost），请改用粘贴方式完成授权：

uv run zendesk-auth --manual

令牌会写入 $XDG_CONFIG_HOME/zendesk-mcp/tokens.json（默认为 ~/.config/zendesk-mcp/tokens.json），并在权限为 0700 的目录中以 0600 权限创建。使用 ZENDESK_TOKEN_FILE 可更改文件位置。此文件包含有效凭据：请像保护密码一样保护它，切勿提交此文件。

令牌续期的工作方式

Zendesk 访问令牌的有效期较短，默认 30 分钟，最长 48 小时， 因此服务会自动为你刷新令牌：

• 到期前，当存储的令牌将在 60 秒内到期时；以及
• 被拒绝时，当 Zendesk 返回 401 和 {"error": "invalid_token"} 时， 此时请求会使用新令牌重试一次。

只有 invalid_token 会触发重试。由于权限范围不足或操作员自身的 Zendesk 权限而返回的 401 或 403 会原样传递，因此权限问题会清晰呈现，不会被误认为是身份验证不稳定。

每次刷新都会轮换刷新令牌，并立即使之前的令牌失效，因此新令牌对会在使用前写入磁盘。 写入操作是原子的，并由锁文件保护；如果你同时从多个 MCP 客户端运行服务，这一点很重要。

当刷新令牌本身过期或被撤销时，工具会报错，并提示操作员重新运行 zendesk-auth。

选择权限范围

默认权限范围涵盖此服务提供的所有工具：

权限范围	用途
tickets:read	get_ticket、get_tickets、get_ticket_comments
tickets:write	create_ticket、update_ticket、create_ticket_comment
ticket_attachments:read	get_ticket_attachment
users:read	工单中的请求者和受派人详情
hc:read	zendesk://knowledge-base 资源

如果你不需要所有工具，可以通过 ZENDESK_OAUTH_SCOPES 缩小权限范围。对于只读访问，可使用 tickets:read users:read hc:read。

权限范围是上限，而不是授权：令牌的权限不会超过授权操作员本身获准使用的权限。请注意，Zendesk 在签发令牌时会接受无法识别的 权限范围名称，但之后会对每个请求都返回 403，因此 zendesk-auth 会打印 Zendesk 实际授予的权限范围，供你对照。

从 API 令牌迁移

Zendesk 正按以下计划淘汰 API 令牌：

日期	变更
2026-07-28	自动停用 30 天未使用的令牌；新账户无法创建令牌。
2026-10-27	所有账户均无法创建新的 API 令牌。
2027-04-30	所有 API 令牌永久停止工作。

在此之前，ZENDESK_EMAIL + ZENDESK_API_KEY 仍可使用，且服务会在首次进行身份验证时记录弃用警告。设置 ZENDESK_CLIENT_ID 后，OAuth 会优先使用，因此你可以迁移而不必删除旧变量。

除了期限要求外，还有一个尽早迁移的理由：Zendesk API 令牌作用于整个账户，且不受权限范围限制。持有令牌的人将获得与该令牌关联用户相同的全部权限，而在大多数部署中，该用户通常是管理员。这正是面向每位操作员的 OAuth 所要解决的问题。

为什么不使用客户端凭据流程？ 它更简单——无需浏览器步骤，也无需刷新令牌——但其令牌会归属于创建 OAuth 客户端的 Zendesk 用户。每位操作员都会以该用户（通常是管理员）的身份执行操作，审计日志和评论署名也都会指向该用户。由于目标是让操作员恰好拥有各自在 Zendesk 中的权限，因此只有授权码流程适用。

Docker

如果你更喜欢隔离的运行环境，可以将服务容器化：

1. 将 .env.example 复制为 .env，并填写 Zendesk 配置。请勿将此文件纳入版本控制。

2. 构建镜像：

   docker build -t zendesk-mcp-server .
   

3. 在主机上授权，而不是在容器中。zendesk-auth 需要浏览器和本地回调端口，因此请在 Docker 外运行一次：

   uv run zendesk-auth
   

4. 运行服务，传入环境文件并挂载令牌存储：

   docker run --rm \
     --env-file /path/to/.env \
     --user "$(id -u):$(id -g)" \
     -e ZENDESK_TOKEN_FILE=/tokens/tokens.json \
     -v "$HOME/.config/zendesk-mcp:/tokens" \
     zendesk-mcp-server
   

   挂载目录必须可写：服务每次轮换刷新令牌时都会重写文件，只读挂载会导致令牌过期后无法继续使用。--user 会让容器以你的身份运行，因此可以读取在主机上创建的 0600 令牌文件。

   将容器接入通过 STDIN/STDOUT 通信的 MCP 客户端时，添加 -i（Claude Code 使用此模式）。对于守护进程运行方式，添加 -d --name zendesk-mcp。

该镜像从 requirements.lock 安装依赖，并以非 root 用户身份运行。使用 API 令牌进行身份验证时，无需挂载卷，因为所有配置都来自环境变量。

Claude MCP 集成

要从 Claude Code/Desktop 使用 Docker 化的服务，请在 Claude Code 的 settings.json 中添加类似以下内容的条目：

{
  "mcpServers": {
    "zendesk": {
      "command": "/usr/local/bin/docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/path/to/zendesk-mcp-server/.env",
        "zendesk-mcp-server"
      ]
    }
  }
}

请根据你的环境调整路径。保存文件后，重启 Claude，以便检测到新的 MCP 服务。

开发

运行测试套件：

uv pip install -e '.[test]'
pytest

测试使用模拟的 HTTP 请求，不会联系 Zendesk。测试涵盖 API 令牌和 OAuth 流程、PKCE 派生、令牌存储与轮换，以及此服务调用 Zendesk 的四种方式。

资源

• zendesk://knowledge-base，获取帮助中心的所有文章。

提示词

analyze-ticket

分析 Zendesk 工单，并提供详细分析。

draft-ticket-response

为 Zendesk 工单撰写回复。

工具

get_tickets

获取最新工单，支持分页

• 输入：

  • page（整数，可选）：页码（默认为 1）
  • per_page（整数，可选）：每页工单数，最多 100（默认为 25）
  • sort_by（字符串，可选）：排序字段，可选 created_at、updated_at、priority 或 status（默认为 created_at）
  • sort_order（字符串，可选）：排序顺序，可选 asc 或 desc（默认为 desc）

• 输出：返回工单列表，包含 id、主题、状态、优先级、描述、时间戳和受理人信息等必要字段，以及分页元数据

get_ticket

根据 ID 获取 Zendesk 工单

• 输入：
  • ticket_id（整数）：要获取的工单 ID

get_ticket_comments

根据 ID 获取 Zendesk 工单的所有评论

• 输入：
  • ticket_id（整数）：要获取评论的工单 ID

create_ticket_comment

为现有 Zendesk 工单创建评论

• 输入：
  • ticket_id（整数）：要添加评论的工单 ID
  • comment（字符串）：要添加的评论文本/内容
  • public（布尔值，可选）：评论是否公开（默认为 true）

create_ticket

创建新的 Zendesk 工单

• 输入：
  • subject（字符串）：工单主题
  • description（字符串）：工单描述
  • requester_id（整数，可选）
  • assignee_id（整数，可选）
  • priority（字符串，可选）：可选值为 low、normal、high、urgent
  • type（字符串，可选）：可选值为 problem、incident、question、task
  • tags（数组[字符串]，可选）
  • custom_fields（数组[对象]，可选）

更新工单

更新现有 Zendesk 工单的字段（例如状态、优先级、负责人）

• 输入：
  • ticket_id（整数）：要更新的工单 ID
  • subject（字符串，可选）
  • status（字符串，可选）：可选值为 new、open、pending、on-hold、solved、closed
  • priority（字符串，可选）：可选值为 low、normal、high、urgent
  • type（字符串，可选）
  • assignee_id（整数，可选）
  • requester_id（整数，可选）
  • tags（数组[字符串]，可选）
  • custom_fields（数组[对象]，可选）
  • due_at（字符串，可选）：ISO8601 日期时间