Zendesk Skill

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令牌

快速开始

# 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令牌
2. 复制令牌（仅显示一次）

# 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（带自动刷新）

1. 在Zendesk中： 管理中心→ 应用程序和集成→ APIs → OAuth客户端→ 添加OAuth客户端
2. 为端口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 和 客户端密钥

# 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

# Check auth status
zd-cli auth status

# Remove credentials
zd-cli auth logout          # API token
zd-cli auth logout-oauth    # OAuth token

安装

通过uvx（建议不安装）

uvx zd-cli --help

uvx 按需在隔离环境中运行该工具——没有任何东西是永久安装的。

通过uv工具安装

uv tool install zendesk-skill
zd-cli --help

开发/Claude代码技能

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

命令

门票

写入操作

默认情况下，所有写入命令都会将Markdown转换为HTML（使用 --plain-text 跳过）。

度量与分析

视图

用户和组织

配置和信息

查询

# 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 从保存的文件中提取数据，而无需重新获取。

搜索查询语法

# 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

安全是 默认启用.在中配置 ~/.config/zd-cli/config.json:

{
  "security_enabled": true,
  "allowlisted_tickets": ["12345", "67890"]
}

• security_enabled --设置为 false 禁用所有筛选和包装（默认值： true)
• allowlisted_tickets --跳过包装的票证ID（适用于受信任/内部票证）

# 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助手提供相同的功能。

uv run zendesk-mcp

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "zendesk": {
      "command": "uvx",
      "args": ["--from", "zendesk-skill", "zendesk-mcp"]
    }
  }
}

发展

uv run pytest -v
uv run zd-cli --help

许可证

麻省理工学院