zendesk-mcp
zendesk-mcp
一个 Model Context Protocol 服务器,向 Claude Code 和其他 MCP 客户端暴露 Zendesk 工单的读取和写入工具。
它能做什么
搜索、列出(分页)和获取 Zendesk 工单、评论和附件
创建新工单并更新现有工单字段(包括组、自定义状态和标签)
发布公开回复和内部备注
设置工单状态并将工单分配给专员
浏览和应用视图与宏
查找用户、组、组织和自定义状态
读取和写入时间跟踪条目
将工单及其对话格式化为 Markdown issue 草稿,以便移交给跟踪器(GitLab、GitHub、Jira)
两个 MCP 提示(
analyze-ticket、draft-ticket-response),用于工单分析和回复起草(可选)将 Zendesk 帮助中心文章作为 MCP 资源暴露
(可选)通过 Git-Zen Zendesk 应用读取关联的 GitLab issues / MRs / commits
Related MCP server: Zendesk MCP Server
前提条件
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权限范围。
安装
安装到项目本地的 virtualenv 中。使用 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系统会提示您输入:
您的 Zendesk 子域名(例如
acme对应acme.zendesk.com)管理员创建的 OAuth 客户端 ID
OAuth 客户端密钥
(可选)Git-Zen 集成字段 ID——参见 可选:Git-Zen 集成
(可选)是否启用帮助中心知识库资源——参见 可选:帮助中心知识库
设置过程会打开浏览器进行 OAuth 授权步骤,然后将令牌写入 ~/.config/zendesk-mcp/config.json(权限模式 0600)。
如果没有浏览器,URL 会打印到终端——您可以在任何设备上打开它,点击 允许,然后将生成的重定向 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 会在每次调用时提示您。
工具
工单
工具 | 说明 |
| 按状态、优先级、类型、受理人、请求者、标签或关键字搜索工单 |
| 分页并排序列出工单(page、per_page、sort_by、sort_order) |
| 获取单个工单的元数据 |
| 创建新工单(subject、description、可选的 priority/type/assignee_id/requester_id/tags/custom_fields) |
| 更新现有工单的一个或多个字段(status、priority、subject、type、assignee_id、requester_id、group_id、custom_status_id、tags、custom_fields、due_at) |
| 获取工单上的对话线程 |
| 列出工单上的附件 |
| 将附件下载到本地缓存目录 |
| 将工单及其对话格式化为 Markdown issue 草稿 |
| 在工单上发布公开回复 |
| 在工单上发布仅专员可见的内部备注 |
| 设置工单状态( |
| 按电子邮件或 |
标签
工具 | 说明 |
| 向工单添加标签(幂等) |
| 从工单移除标签(幂等) |
视图与宏
工具 | 说明 |
| 列出所有启用的视图 |
| 获取视图的筛选条件和执行设置 |
| 获取当前匹配某个视图的工单 |
| 列出启用的宏及其操作 |
| 预览宏将做出的更改 |
| 对工单应用宏(应用字段更改并发布任何评论) |
用户、组与组织
工具 | 说明 |
| 按姓名或电子邮件查找用户 |
| 列出所有启用的组 |
| 列出组成员 |
| 获取组织(包括自定义字段) |
| 列出所有自定义工单状态及其 ID |
时间跟踪
工具 | 说明 |
| 读取工单的时间跟踪条目 |
| 为工单记录时间条目 |
Git-Zen 集成
工具 | 说明 |
| (仅 Git-Zen)获取工单关联的 GitLab issues / MRs / commits |
提示
服务器暴露两个 MCP 提示,某些客户端(例如 Claude Desktop)会将其显示为斜杠命令:
提示 | 参数 | 说明 |
|
| 要求模型获取工单并生成摘要、状态/时间线以及关键交互点 |
|
| 要求模型获取工单并起草面向客户的回复(发布前有确认步骤) |
可选: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 会返回一条 "not configured" 消息。
可选:帮助中心知识库
如果您的 Zendesk 实例有已发布的帮助中心,您可以将其版块和文章作为 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 的实例的服务器资源列表将保持为空。
开发
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许可证
Available Tools
29 toolszendesk_add_tagA
Add a tag to a Zendesk ticket. Idempotent: adding an existing tag returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.
Inputs: tag (required), ticket_id (required). Returns: result
zendesk_apply_macroA
Apply a macro to a Zendesk ticket. Fetches the macro preview, applies field changes, and posts any comment included in the macro. Returns JSON with id, status, tags, applied_changes, comment_added.
Inputs: macro_id (required), ticket_id (required). Returns: result
zendesk_assign_ticketA
Assign a Zendesk ticket to an agent by their email address. Pass 'me' as assignee_email to assign the ticket to yourself (the authenticated user).
Inputs: ticket_id (required), assignee_email (required). Returns: result
zendesk_create_ticketA
Create a new Zendesk ticket. subject and description are required. priority: low/normal/high/urgent. type: problem/incident/question/task. requester_id/assignee_id are user IDs (integers). custom_fields is a list of {id, value} dicts. Returns JSON of the created ticket.
Inputs: subject (required), description (required), tags, type, +4 more. Returns: result
zendesk_download_attachmentA
Download a Zendesk attachment. Obtain attachment_url and filename from zendesk_list_attachments. ticket_id is required for cache organization. Optional dest_dir overrides the default cache location; the file is written there and (for archives) extracted alongside it. Archives return a file list and unpack_dir — read individual files with your normal file tools. PDFs return up to ~500KB of extracted text. Images are base64-encoded.
Inputs: filename (required), ticket_id (required), attachment_url (required), dest_dir. Returns: result
zendesk_get_commentsA
Get all comments (public replies and internal notes) for a Zendesk ticket. Includes attachment metadata but does not download files.
Inputs: ticket_id (required). Returns: result
zendesk_get_git_zen_linksA
Get linked GitLab issues, merge requests, and commits for a Zendesk ticket via the Git-Zen integration. Returns structured lists with state, labels, weight, and direct GitLab links.
Inputs: ticket_id (required). Returns: result
zendesk_get_groupsA
List all active Zendesk groups (excluding deleted). Returns JSON array of {id, name}.
Inputs: no named parameters. Returns: result
zendesk_get_group_usersB
List the members of a Zendesk group. Returns JSON array of {id, name, email}.
Inputs: group_id (required). Returns: result
zendesk_get_organizationB
Fetch a Zendesk organization including its custom fields and tags. Returns JSON with id, name, organization_fields, tags, created_at, updated_at.
Inputs: organization_id (required). Returns: result
zendesk_get_ticketA
Get a Zendesk ticket by ID. Returns ticket fields including status, priority, requester, assignee, tags, and description.
Inputs: ticket_id (required). Returns: result
zendesk_get_ticketsA
List Zendesk tickets with pagination. page: 1-based page number. per_page: max 100. sort_by: created_at, updated_at, priority, or status. sort_order: asc or desc. Returns tickets plus pagination metadata.
Inputs: page, sort_by, per_page, sort_order. Returns: result
zendesk_get_time_trackingA
Get time tracking data for a Zendesk ticket. Returns total time spent and time spent on the last update, in both seconds and human-readable format (e.g. '2h 15m').
Inputs: ticket_id (required). Returns: result
zendesk_get_viewA
Get a Zendesk view's definition including filter conditions and execution settings. Returns JSON with id, title, active, conditions, execution.
Inputs: view_id (required). Returns: result
zendesk_get_view_ticketsB
Get the tickets currently matching a Zendesk view. Returns JSON array of tickets with essential fields.
Inputs: view_id (required). Returns: result
zendesk_list_attachmentsA
List all attachments across all comments for a Zendesk ticket. Returns filename, content type, size, and download URL for each. Use zendesk_download_attachment to fetch file contents.
Inputs: ticket_id (required). Returns: result
zendesk_list_custom_statusesA
List all custom ticket statuses defined in Zendesk. Returns JSON array of {id, agent_label, end_user_label, status_category, active, default}. Use the id when setting custom_status_id on a ticket.
Inputs: no named parameters. Returns: result
zendesk_list_macrosA
List all active Zendesk macros with their actions. Returns JSON array of {id, title, description, actions: [{field, value}]}.
Inputs: no named parameters. Returns: result
zendesk_list_viewsA
List all active Zendesk views. Returns JSON array of {id, title}.
Inputs: no named parameters. Returns: result
zendesk_log_timeA
Log time spent on a Zendesk ticket. Adds seconds to the running total and records it as the last-update time. Returns logged amount and new total in seconds and human-readable format.
Inputs: seconds (required), ticket_id (required). Returns: result
zendesk_post_commentA
Post a public reply on a Zendesk ticket. The reply is visible to the requester. Use for customer-facing responses.
Inputs: body (required), ticket_id (required). Returns: result
zendesk_post_internal_noteA
Post an internal note on a Zendesk ticket. Internal notes are only visible to agents and are not sent to the requester.
Inputs: body (required), ticket_id (required). Returns: result
zendesk_preview_macroA
Preview the effect a macro would have (without applying it). Returns the result payload from Zendesk's apply preview endpoint.
Inputs: macro_id (required). Returns: result
zendesk_remove_tagA
Remove a tag from a Zendesk ticket. Idempotent: removing a tag that isn't present returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.
Inputs: tag (required), ticket_id (required). Returns: result
zendesk_search_ticketsA
Search Zendesk tickets by keyword and/or status. keywords: free-text search (e.g. 'login failure LDAP'). status: new, open, pending, hold, solved, closed — leave empty for all statuses. Returns id, subject, status, requester, assignee, and dates.
Inputs: limit, status, keywords. Returns: result
zendesk_search_usersA
Search Zendesk users by name or email. Returns JSON array of {id, name, email, role}.
Inputs: query (required). Returns: result
zendesk_set_ticket_statusB
Set the status of a Zendesk ticket. Valid statuses: new, open, pending, hold, solved, closed.
Inputs: status (required), ticket_id (required). Returns: result
zendesk_ticket_to_gitlab_contextA
Format a Zendesk ticket and its comments as an issue draft. Returns Markdown with ticket metadata, full conversation, and an empty Steps to Reproduce section. Use this output as the description when creating an issue in your tracker.
Inputs: ticket_id (required). Returns: result
zendesk_update_ticketA
Update one or more fields on a Zendesk ticket. Pass only the fields you want to change. status: new/open/pending/hold/solved/closed. priority: low/normal/high/urgent. type: problem/incident/question/task. assignee_id, requester_id, group_id, custom_status_id are integer IDs. due_at is ISO8601. Returns JSON of the refreshed ticket.
Inputs: ticket_id (required), tags, type, due_at, +8 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Each tool has a clearly distinct purpose, even where operations appear similar (e.g., get_ticket, get_tickets, search_tickets). Descriptions clarify when to use each, and there is no meaningful overlap that would cause an agent to select the wrong tool.
All tools share the 'zendesk_' prefix and mostly follow a verb_noun pattern. There is some mixing between 'get_' and 'list_' for read operations, but overall the conventions are predictable and easy to follow.
With 29 tools, this exceeds the 25-tool threshold for a 'too many' rating. While the scope is broad, the high count makes the surface feel heavy and increases selection complexity, even though each tool is well-scoped individually.
The server covers the full ticket lifecycle including comments, attachments, time tracking, views, and macros. Minor gaps exist such as lack of ticket deletion and user management, but core support workflows are well represented.
Maintenance
Related MCP Connectors
Read tickets, users, orgs, macros and satisfaction ratings; create, update and comment on tickets.
Search and read Zammad tickets, customers and organizations; add notes, replies and ticket updates.
Read tickets, contacts, companies, agents and groups; create, update and reply to tickets.
Work with Enchant help desk tickets: list, read, reply, add notes and labels, manage customers.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Zendesk to manage tickets, retrieve ticket fields, comments, and priority based on SLA, as well as get unsolved tickets by agent name.1-
- FlicenseNot gradedqualityAmaintenanceEnables users to fetch, create, and update Zendesk tickets and comments, analyze tickets and draft responses, and query Help Center articles as a knowledge base.-
- FlicenseNot gradedqualityAmaintenanceEnables integration with Zendesk to retrieve and manage tickets and comments, analyze tickets, draft responses, and access Help Center articles as a knowledge base.-
- FlicenseNot gradedqualityAmaintenanceEnables retrieving and managing Zendesk tickets and comments, accessing Help Center articles as a knowledge base, and using specialized prompts for ticket analysis and response drafting.-