Zendesk CLI、MCP服务器和Claude代码技能
Zendesk支持集成的Claude代码技能。主界面是 技能档案 (SKILL.md)这为Claude提供了完整的命令知识——由CLI支持(zd-cli)Claude运行它与Zendesk进行交互。MCP服务器也包含在其他AI助手中。
> 这个项目几乎完全是由Claude Code通过迭代对话构建的——针对实时Zendesk实例进行设计、实现、测试,并在多个会话中一起修复问题。这是我经常使用的工具,如果其他人觉得它有用,我会分享它。
特性
- Claude代码技能 —
SKILL.md为Claude提供完整的命令文档、工作流和先保存后查询模式 - CLI(
zd-cli) --28个命令,涵盖票证、用户、组织、视图、指标等 - MCP服务器 --其他AI助手的替代界面
- Slack 集成 --向Slack频道发送格式化的支持报告
- 支持指标分析 --响应时间、分辨率、CSAT、下班后和随叫随到跟踪
- 本地响应存储 -API响应保存到临时目录,可使用jq查询,无需重新查找
- Markdown 格式 --写操作将Markdown转换为HTML,以便在代理工作区中正确呈现
- 加密凭证 -休息时加密的API令牌和OAuth令牌
快速开始```bash
Run directly (no install needed)
uvx zd-cli --help
Set up credentials (see Authentication below)
uvx zd-cli auth login
Verify it works
uvx zd-cli me
## 认证
支持三种方法。API令牌是最简单的;OAuth添加了自动刷新功能。共享团队部署存在中继服务器模式,但此处不涉及。
### 方法一:API代币
1. 在Zendesk中: **管理中心→ 应用程序和集成→ APIs → API Zendesk→ 添加API令牌**
1. 复制令牌(仅显示一次)```bash
# Interactive setup (prompts for email, token, subdomain)
zd-cli auth login
# Or non-interactive
zd-cli auth login --email you@company.com --token YOUR_TOKEN --subdomain yourcompany
# Or via environment variables
export ZENDESK_EMAIL="you@company.com"
export ZENDESK_TOKEN="your-api-token"
export ZENDESK_SUBDOMAIN="yourcompany"
方法2:OAuth 2.0(带自动刷新)
- 在Zendesk中: 管理中心→ 应用程序和集成→ APIs → OAuth客户端→ 添加OAuth客户端
- 为端口8080–8089添加重定向URI:```
http://127.0.0.1:8080/callback
http://127.0.0.1:8081/callback
...
http://127.0.0.1:8089/callback
1. 注意 **客户端ID** 和 **客户端密钥**```bash
# Opens a browser for authorization
zd-cli auth login-oauth --subdomain yourcompany --client-id YOUR_ID --client-secret YOUR_SECRET
# Headless/SSH: browser redirects to localhost (shows connection refused — that's expected),
# paste the full redirect URL back into the prompt
zd-cli auth login-oauth --subdomain yourcompany --client-id YOUR_ID --client-secret YOUR_SECRET --manual
``````bash
# Check auth status
zd-cli auth status
# Remove credentials
zd-cli auth logout # API token
zd-cli auth logout-oauth # OAuth token
安装
通过uvx(建议不安装)```bash
uvx zd-cli --help
`uvx` 按需在隔离环境中运行该工具——没有任何东西是永久安装的。
### 通过uv工具安装```bash
uv tool install zendesk-skill
zd-cli --help
开发/Claude代码技能```bash
git clone https://github.com/andmarios/zendesk-skill zendesk-skill
cd zendesk-skill
uv sync
uv run zd-cli --help
克劳德代码点 `SKILL.md` 为Claude提供完整的命令文档和工作流程。
**先决条件:** Python 3.12+, 紫外线,以及 `jq` (为 `query` 命令)。
## 命令
### 门票
|命令|描述|
|---------|-------------|
| `search "status:open priority:urgent"` |搜索门票|
| `ticket 12345` |凭身份证购票|
| `ticket-details 12345` |门票+所有评论|
| `linked-incidents 12345` |与问题工单相关的事件|
| `attachment --ticket 12345 ` |下载附件|
### 写入操作
默认情况下,所有写入命令都会将Markdown转换为HTML(使用 `--plain-text` 跳过)。
|命令|描述|
|---------|-------------|
| `update-ticket 12345 --status pending --tags "waiting-customer"` |更新工单|
| `create-ticket "Subject" "**Bold** description"` |创建工单|
| `add-note 12345 "Internal **note**"` |添加内部注释|
| `add-comment 12345 "Public reply"` |添加公众评论|
### 度量与分析
|命令|描述|
|---------|-------------|
| `ticket-metrics 12345` |工单的回复/解决时间|
| `list-metrics` |门票指标|
| `satisfaction-ratings --score bad` CSAT评级
### 视图
|命令|描述|
|---------|-------------|
| `views` |列出可用视图|
| `view-count 123` |视图中的票计数|
| `view-tickets 123` |门票从一个观点|
### 用户和组织
|命令|描述|
|---------|-------------|
| `user 12345` |按ID获取用户|
| `search-users "john@example.com"` |搜索用户|
| `org 67890` |按ID获取组织|
| `search-orgs "Acme"` |搜索组织|
### 配置和信息
|命令|描述|
|---------|-------------|
| `me` |当前用户(测试身份验证)|
| `groups` |列出支持小组|
| `tags` |热门标签|
| `sla-policies` |SLA政策|
### 查询```bash
# Query a saved response file with jq
zd-cli query -q comments_slim # named query
zd-cli query --jq '.data.ticket' # custom jq
zd-cli query --list # show available named queries
所有命令都将其完整的API响应保存到 /tmp/zd-cli-$UID/ 并打印路径。使用 zd-cli query 从保存的文件中提取数据,而无需重新获取。
搜索查询语法```bash
Status & priority
zd-cli search "status:open priority:urgent"
zd-cli search "status:pending assignee:me"
Time filters
zd-cli search "created>2024-01-01 status:open"
zd-cli search "updated<1week status:open"
By person/org
zd-cli search "requester:user@example.com status:open"
zd-cli search "organization:acme type:incident"
Tags
zd-cli search "tags:billing tags:escalated"
## Slack集成```bash
# Configure
zd-cli auth login-slack --webhook "https://hooks.slack.com/services/..." --channel "#support"
# Send a report
zd-cli slack-report
# Check / remove
zd-cli auth status-slack
zd-cli auth logout-slack
支持指标分析```bash
Default: last 2 weeks
uv run python src/zendesk_skill/scripts/analyze_support_metrics.py
Custom range with accurate reply counts from the Ticket Metrics API
uv run python src/zendesk_skill/scripts/analyze_support_metrics.py \
--start 2026-01-01 --end 2026-01-15 --fetch-metrics
Pipe to Slack
uv run python src/zendesk_skill/scripts/analyze_support_metrics.py | zd-cli slack-report
Generate markdown report
zd-cli markdown-report -o report.md
### 营业时间和随叫随到跟踪
在中配置 `~/.config/zd-cli/config.json` 在您的报告中添加下班后和随叫随到部分:```json
{
"business_hours": {
"timezone": "Europe/Berlin",
"start_hour": 9,
"end_hour": 18,
"workdays": [0, 1, 2, 3, 4]
},
"oncall": {
"enabled": true,
"start_hour": 19,
"end_hour": 9,
"customers": ["bigclient.com"],
"priorities": ["urgent"]
}
}
配置后,报告包括下班后的工单计数、消息、回复和随叫随到的约定(在随叫随叫时间内与配置的优先级+客户域匹配的工单)。随叫随到门票的首次登记税按日历时间计算;所有其他人都使用营业时间。
安全:快速注射保护
Zendesk的所有内容都被视为不受信任的输入,并在到达LLM之前通过多层安全管道进行筛选:
- 正则表达式检测 --已知的提示注射模式(指令覆盖、提示提取、leetspeak规避)
- 语义匹配 --已知注射模板的模糊相似性
- 俳句/LLM筛选 --配置后,基于LLM的分类器用于复杂攻击
每个面向LLM的字段(票主题、评论正文、用户名、电子邮件、组织名称、视图标题)都用会话范围的安全标记包装。存储的响应文件也会在保存时使用正则表达式和语义筛选层进行扫描,检测结果保存在文件元数据中。
附件扫描 了解尺寸:
- 高达1 MB的文本文件通过全屏管道进行内联扫描
- 超过1 MB的文本文件和二进制文件会收到安全警告,并提示使用CLI工具手动扫描:```bash
uvx prompt-security-utils
安全是 **默认启用**.在中配置 `~/.config/zd-cli/config.json`:```json
{
"security_enabled": true,
"allowlisted_tickets": ["12345", "67890"]
}
security_enabled--设置为false禁用所有筛选和包装(默认值:true)allowlisted_tickets--跳过包装的票证ID(适用于受信任/内部票证)```bash
View current security status and session markers
zd-cli security-info
Include full MCP security instructions
zd-cli security-info --instructions
需要 `prompt-security-utils` (作为依赖项包含在内)。
## MCP服务器
MCP服务器为支持模型上下文协议的AI助手提供相同的功能。```bash
uv run zendesk-mcp
添加 claude_desktop_config.json:```json
{
"mcpServers": {
"zendesk": {
"command": "uvx",
"args": ["--from", "zendesk-skill", "zendesk-mcp"]
}
}
}
## 发展```bash
uv run pytest -v
uv run zd-cli --help
许可证
麻省理工学院
