内容
# zendesk-mcp
一个遵循[模型上下文协议](https://modelcontextprotocol.io)的服务器，旨在向[Claude Code](https://claude.com/claude-code)和其他MCP客户端公开Zendesk工单的读取和写入工具。
## 功能
- 搜索、列出（分页）和获取Zendesk工单、评论和附件
- 创建新的工单和更新现有的工单字段（包括组、自定义状态和标签）
- 发布公开回复和内部备注
- 设置工单状态并将工单分配给代理人
- 浏览和应用视图和宏
- 查询用户、组、组织和自定义状态
- 读取和写入时间跟踪记录
- 将工单格式化为Markdown问题草稿，以便移交给跟踪器（GitLab、GitHub、Jira）
- 两个MCP提示（`analyze-ticket`、`draft-ticket-response`），用于工单分析和响应草拟
- （可选）将Zendesk帮助中心文章作为MCP资源公开
- （可选）通过[Git-Zen](https://www.zendesk.com/marketplace/apps/support/630175/git-zen-zendesk-and-gitlab-integration/) Zendesk应用读取链接的GitLab问题/MRs/提交
## 先决条件
- 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和其他项目隔离，这是下面所有步骤的推荐路径。
从此存储库的克隆：
```bash
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .
```
用于开发（同时安装pytest）：
```bash
.venv/bin/pip install -e ".[dev]"
```
> 在整个README中，命令使用venv的二进制文件通过`.venv/bin/...`。您也可以在每个shell中`source .venv/bin/activate`一次并删除前缀——结果相同。
## OAuth设置
使用venv的Python运行交互式设置：
```bash
.venv/bin/python -m zendesk_mcp setup
```
您将被提示：
1. 您的Zendesk子域名（例如`acme`表示`acme.zendesk.com`）
2. 由管理员创建的OAuth客户端ID
3. OAuth客户端密钥
4. （可选）Git-Zen集成字段ID - 请参阅[可选：Git-Zen集成](#可选git-zen集成)
5. （可选）是否启用帮助中心知识库资源 - 请参阅[可选：帮助中心知识库](#可选帮助中心知识库)
设置会打开一个浏览器进行OAuth授权步骤，然后将令牌写入`~/.config/zendesk-mcp/config.json`（模式`0600`）。
如果您没有浏览器，URL将被打印到终端 - 在任何设备上打开它，点击**允许**，然后将生成的重定向URL粘贴回提示中。
## 注册到Claude Code
使用venv的Python通过绝对路径注册MCP服务器。Claude Code在新shell中启动服务器，该shell不会继承您的激活venv，因此需要绝对路径 - 直接指向裸`python`将无法导入`zendesk_mcp`。
```bash
ZENDESK_MCP_DIR="$(pwd)" # 从仓库根目录运行，安装后
claude mcp add --scope user zendesk -- "$ZENDESK_MCP_DIR/.venv/bin/python" -m zendesk_mcp
```
或者直接使用绝对路径：
```bash
claude mcp add --scope user zendesk -- /absolute/path/to/zendesk-mcp/.venv/bin/python -m zendesk_mcp
```
然后在`~/.claude/settings.json`中将读取工具添加到`permissions.allow`中，以避免每次调用的提示：
```json
{
"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将为您提示每次调用。
## 工具
### 工单
| 工具 | 功能 |
|---|---|
| `zendesk_search_tickets` | 按状态、优先级、类型、分配人、请求者、标签或关键词搜索工单 |
| `zendesk_get_tickets` | 列出工单，支持分页和排序（页码，每页数量，排序字段，排序顺序） |
| `zendesk_get_ticket` | 获取一个工单的元数据 |
| `zendesk_create_ticket` | 创建一个新的工单（主题，描述，可选优先级/类型/分配人ID/请求者ID/标签/自定义字段） |
| `zendesk_update_ticket` | 更新一个或多个现有工单的字段（状态，优先级，主题，类型，分配人ID，请求者ID，组ID，自定义状态ID，标签，自定义字段，到期时间） |
| `zendesk_get_comments` | 获取一个工单的对话线程 |
| `zendesk_list_attachments` | 列出一个工单的附件 |
| `zendesk_download_attachment` | 下载附件到本地缓存目录 |
| `zendesk_ticket_to_gitlab_context` | 将一个工单及其对话格式化为Markdown问题草稿 |
| `zendesk_post_comment` | 在一个工单上发布公开回复 |
| `zendesk_post_internal_note` | 在一个工单上发布仅限代理人阅读的内部备注 |
| `zendesk_set_ticket_status` | 设置工单状态（`new`、`open`、`pending`、`hold`、`solved`、`closed`） |
| `zendesk_assign_ticket` | 按电子邮件或`me`将工单分配给代理人 |
### 标签
| 工具 | 功能 |
|---|---|
| `zendesk_add_tag` | 向一个工单添加标签（幂等） |
| `zendesk_remove_tag` | 从一个工单中删除标签（幂等） |
### 视图和宏
| 工具 | 功能 |
|---|---|
| `zendesk_list_views` | 列出所有活动视图 |
| `zendesk_get_view` | 获取一个视图的筛选条件和执行设置 |
| `zendesk_get_view_tickets` | 获取当前匹配一个视图的工单 |
| `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问题/MRs/提交 |
## 提示
服务器公开了两个MCP提示，一些客户端（例如Claude Desktop）将其作为斜杠命令显示：
| 提示 | 参数 | 功能 |
|---|---|---|
| `analyze-ticket` | `ticket_id` | 请求模型获取工单并生成摘要、状态/时间线和关键交互点 |
| `draft-ticket-response` | `ticket_id` | 请求模型获取工单并草拟面向客户的回复（在发布前进行确认步骤） |
## 可选：Git-Zen集成
如果您的Zendesk实例使用[Git-Zen](https://www.zendesk.com/marketplace/apps/support/630175/git-zen-zendesk-and-gitlab-integration/)应用，`zendesk_get_git_zen_links`工具可以读取其自定义字段有效载荷。在**管理员 → 工单 → 字段**下找到您实例的Git-Zen自定义字段ID（它是一个数字ID），然后在`.venv/bin/python -m zendesk_mcp setup`期间设置它，或编辑`~/.config/zendesk-mcp/config.json`添加：
```json
{
"git_zen_field_id": 12345678901234
}
```
如果未配置此项，`zendesk_get_git_zen_links`将返回一条“未配置”的消息。
## 可选：帮助中心知识库
如果您的Zendesk实例有一个已发布的帮助中心，您可以将它的章节和文章作为`zendesk://knowledge-base` MCP资源公开。该资源返回一个涵盖所有章节和文章的单个JSON文档，缓存一小时。
这是可选的。您可以通过在`.venv/bin/python -m zendesk_mcp setup`期间选择“y”，或将以下内容添加到`~/.config/zendesk-mcp/config.json`中来启用它：
```json
{
"knowledge_base_enabled": true
}
```
当标志不存在或为false时，资源未注册，保持服务器的资源列表为空，以适应没有帮助中心的实例。
## 开发
```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
```
测试在Python 3.10、3.11和3.12上运行，参见`.github/workflows/test.yml`。
## 许可证
[Apache-2.0](LICENSE)
<!-- mcp-name: io.github.michaelrice/zendesk-mcp -->
