内容
# zendesk-ops-mcp
一款提供基于Zendesk Support API的运维工具的MCP服务器 — 工单分类、SLA监控、代理工作量分析和系统健康审计。专为与 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 Claude Desktop 一起使用而设计，它为支持运维团队提供了一个对话式界面，以自动化管理Zendesk工作流的手动操作。
## 快速开始
```bash
git clone https://github.com/avg-ape/zendesk-ops-mcp.git
cd zendesk-ops-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```
配置您的Zendesk凭证：
```bash
cp .env.example .env
# 编辑.env文件，填写您的子域名、邮箱和API令牌
```
您可以在 [zendesk.com/register](https://www.zendesk.com/register/) 获取免费的Zendesk试用版。在Admin Center > Apps & Integrations > APIs中启用API令牌。
### 与Claude Code一起使用
将以下内容添加到您的Claude Code MCP配置（`~/.claude/settings.json`）：
```json
{
"mcpServers": {
"zendesk-ops": {
"command": "/path/to/zendesk-ops-mcp/.venv/bin/python",
"args": ["-m", "zendesk_ops_mcp.server"],
"env": {
"ZENDESK_SUBDOMAIN": "your-subdomain",
"ZENDESK_EMAIL": "your-email@example.com",
"ZENDESK_API_TOKEN": "your-api-token"
}
}
}
}
```
然后询问Claude类似的问题：
- "分类开放工单 — 哪些缺少指派者或优先级？"
- "显示我过去12小时内已经过时的工单"
- "过去30天的CSAT评分是多少，按代理人分类？"
- "审计我们的宏 — 是否有重复或未使用的宏？"
- "哪些代理人当前工作量过载？"
## 工具
| 工具 | 描述 |
|------|-------------|
| `ticket_triage` | 查找缺少指派者、分组或优先级的工单 |
| `stale_ticket_report` | 指定时间内无更新的工单，按分组/优先级分类 |
| `bulk_tag_tickets` | 为匹配搜索查询的工单添加标签（默认为干预运行） |
| `bulk_close_tickets` | 关闭旧的已解决/待处理工单（默认为干预运行） |
| `sla_breach_report` | 违反或接近SLA目标的工单 |
| `csat_summary` | 指定时间内的满意度评分，按代理人分类 |
| `response_time_analysis` | 首答和解决时间平均值 |
| `agent_workload` | 代理人开放工单数量及优先级分类 |
| `group_distribution` | 分组间的工单数量和状态分类 |
| `macro_audit` | 查找未使用或重复的宏 |
| `trigger_review` | 审计活跃的触发器和自动化 |
## 架构
**Zendesk客户端（`zendesk_client.py`）：** 基于`httpx`的异步HTTP客户端，支持基本认证（API令牌）。处理偏移分页（`next_page`）和搜索端点的游标分页。 通过`X-RateLimit-Remaining`头部跟踪速率限制。
**Pydantic模型（`models.py`）：** 所有工具输出均为类型化的Pydantic模型，包含人类可读的`__str__`方法。Claude获取结构化数据以进行推理，而不是原始JSON。
**双重分页：** Zendesk对列表端点（`/api/v2/tickets.json`）使用偏移分页，对搜索端点使用特定分页。客户端通过`get_all()`和`search()`方法透明地处理两者。
## 开发
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行单元测试
pytest tests/ -v
# 运行集成测试（需要Zendesk凭证）
pytest tests/ -v --integration
```
## 许可证
MIT
