zendesk-mcp

一个 Model Context Protocol 服务器，用于向 Claude Code 和其他 MCP 客户端公开 Zendesk 工单的读写工具。

功能

• 搜索并获取 Zendesk 工单、评论和附件

• 发布公开回复和内部备注

• 设置工单状态并将工单分配给客服人员

• 读取和写入工时记录

• 将工单格式化为 Markdown 问题草稿，以便移交给跟踪系统（GitLab、GitHub、Jira）

• （可选）通过 Git-Zen Zendesk 应用读取关联的 GitLab 问题/合并请求/提交

前置要求

• 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，对应 acme.zendesk.com）

2. 管理员创建的 OAuth 客户端 ID

3. OAuth 客户端密钥

4. （可选）Git-Zen 集成字段 ID — 参见 可选：Git-Zen 集成

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

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

在 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_comments",
      "mcp__zendesk__zendesk_list_attachments",
      "mcp__zendesk__zendesk_download_attachment",
      "mcp__zendesk__zendesk_search_tickets",
      "mcp__zendesk__zendesk_ticket_to_gitlab_context"
    ]
  }
}

写入工具（zendesk_post_comment、zendesk_post_internal_note、zendesk_set_ticket_status、zendesk_assign_ticket、zendesk_log_time）默认不在允许列表中 — Claude 会在每次调用时提示你。

工具

可选：Git-Zen 集成

如果你的 Zendesk 实例使用了 Git-Zen 应用，zendesk_get_git_zen_links 工具可以读取其自定义字段负载。在 管理 → 工单 → 字段 下找到你实例的 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 将返回“未配置”消息。

开发

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）。

许可证

Apache-2.0