内容
# Zendesk 只读 MCP 服务器
一个免费、可克隆的模型上下文协议（MCP）服务器，允许 Claude Desktop、Cursor、自定义应用程序和其他 MCP 兼容的客户端通过只读工具查询 Zendesk。
## 功能
该服务器通过存储在本地环境变量中的 API 令牌连接到 Zendesk REST API。它提供了安全的只读工具，用于常见的支持分析工作：
- 使用 Zendesk 搜索语法搜索工单、用户和组织
- 按状态、组、分配人、排序顺序和页面列出工单
- 获取完整的工单详细信息，包括评论线程上下文
- 列出和检查用户、组织、组和视图
- 检查工单字段、触发器和宏
- 调用额外的只读 Zendesk API v2 `.json` 端点，无需编写新的工具
- 以可读的 Markdown 或结构化的 JSON 返回结果
## 安全措施
- 设计为只读
- 无创建、更新、删除、合并、解决或请求者更改工具
- 存储库中无机密信息
- Zendesk 凭证由本地 MCP 客户端配置提供
- 使用 Pydantic 验证工具输入
## 要求
- Python 3.10+
- Zendesk API 令牌
- Claude Desktop、Cursor、自定义应用程序或其他支持运行本地 stdio MCP 服务器的 MCP 兼容客户端
安装依赖项：
```bash
pip install -r requirements.txt
```
## Zendesk 凭证
在 Zendesk 管理中心创建 Zendesk API 令牌：
1. 打开管理中心
2. 进入应用程序和集成
3. 打开 Zendesk API
4. 启用令牌访问
5. 添加 API 令牌
使用 `.env.example` 作为必填值的参考：
```bash
ZENDESK_SUBDOMAIN=您的子域名
ZENDESK_EMAIL=admin@example.com
ZENDESK_API_TOKEN=您的 Zendesk API 令牌
```
不要提交 `.env` 或实际令牌。
## MCP 客户端设置
此存储库作为本地 stdio MCP 服务器运行。任何支持 stdio MCP 服务器的客户端都需要相同的 基本值：
- `command`: `python3`
- `args`: `zendesk_mcp.py` 的绝对路径
- `env`: Zendesk 凭证
### Claude Desktop
将服务器添加到 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"zendesk": {
"command": "python3",
"args": [
"/绝对路径/to/zendesk_mcp.py"
],
"env": {
"ZENDESK_SUBDOMAIN": "您的子域名",
"ZENDESK_EMAIL": "admin@example.com",
"ZENDESK_API_TOKEN": "您的令牌"
}
}
}
}
```
保存配置后重启 Claude Desktop。
### Cursor 或其他基于 JSON 的 MCP 客户端
对于接受 MCP 服务器 JSON 配置的客户端，使用相同的服务器块：
```json
{
"mcpServers": {
"zendesk": {
"command": "python3",
"args": [
"/绝对路径/to/zendesk_mcp.py"
],
"env": {
"ZENDESK_SUBDOMAIN": "您的子域名",
"ZENDESK_EMAIL": "admin@example.com",
"ZENDESK_API_TOKEN": "您的令牌"
}
}
}
}
```
一些客户端使用工作区级 `mcp.json`，而其他客户端使用全局设置文件。服务器块保持不变。
### 自定义应用程序
自定义应用程序可以将此服务器作为子进程运行，并使用支持 stdio 传输的任何 MCP 客户端 SDK 连接。 将 Zendesk 凭证保存在源代码控制之外，并在进程启动时将它们作为环境变量注入。
实施检查清单：
1. 以 `python3 /绝对路径/to/zendesk_mcp.py` 启动作为 stdio MCP 服务器。
2. 在进程环境中传递 `ZENDESK_SUBDOMAIN`、`ZENDESK_EMAIL` 和 `ZENDESK_API_TOKEN`。
3. 初始化 MCP 客户端会话。
4. 列出工具并调用应用程序工作流程所需的 Zendesk 工具。
5. 除非添加 OAuth、租户隔离、审计日志和加密令牌存储，否则请保持服务器本地或单租户。
### ChatGPT 或仅远程 MCP 客户端
一些客户端支持远程 MCP 服务器而不是本地 stdio 服务器。此存储库默认情况下是本地 stdio 服务器。要与仅远程客户端一起使用，请将其包装或部署在远程 MCP 传输后面，并添加适当的生产控件：
- OAuth 或另一个明确的授权流程
- 加密的 Zendesk 令牌存储
- 租户隔离
- 每个工具调用的审计日志
- 速率限制
- 撤销流程
在没有这些控件的情况下，不要公开暴露基于本地 API 令牌的服务器。
## 可用工具
| 工具 | 用途 |
| --- | --- |
| `zendesk_search` | 跨工单、用户和组织的统一搜索 |
| `zendesk_list_tickets` | 按状态、组和分配人筛选的工单列表 |
| `zendesk_get_ticket` | 获取完整的工单详细信息和评论 |
| `zendesk_list_users` | 按角色或组织列出用户 |
| `zendesk_get_user` | 获取完整的用户信息 |
| `zendesk_list_organizations` | 列出组织 |
| `zendesk_get_organization` | 获取完整的组织信息 |
| `zendesk_list_groups` | 列出代理组 |
| `zendesk_list_views` | 列出视图和视图配置 |
| `zendesk_get_view_tickets` | 列出当前在视图中的工单 |
| `zendesk_list_ticket_fields` | 列出工单字段和值 |
| `zendesk_list_triggers` | 按活动/非活动状态列出触发器 |
| `zendesk_get_trigger` | 获取完整的触发器条件和操作 |
| `zendesk_list_macros` | 列出宏和范围 |
| `zendesk_get_endpoint` | 调用额外的只读 Zendesk API v2 `.json` 端点 |
## 添加更多端点
存储库支持两条扩展路径。
### 选项 1：使用通用只读端点工具
对于尚未建模的 Zendesk API v2 端点，请使用 `zendesk_get_endpoint`:
```json
{
"endpoint": "brands.json",
"params": {
"page": 1,
"per_page": 25
},
"response_format": "json"
}
```
规则：
- 仅使用相对端点，例如 `brands.json` 或 `help_center/articles.json`
- 不要包含完整 URL
- 不要在端点中包含查询字符串；将查询参数放在 `params` 中
- 仅接受 `.json` 端点
- 服务器仍然只发出 GET 请求
### 选项 2：添加类型化工具
对于经常使用的端点，请添加专用的 Pydantic 输入模型和 MCP 工具：
```python
class ListBrandsInput(BaseModel):
model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True, extra="forbid")
response_format: ResponseFormat = Field(default=ResponseFormat.MARKDOWN)
@mcp.tool(
name="zendesk_list_brands",
annotations={
"title": "列出 Zendesk 品牌",
"readOnlyHint": True,
"destructiveHint": False,
"idempotentHint": True,
"openWorldHint": True,
},
)
async def zendesk_list_brands(params: ListBrandsInput) -> str:
try:
data = await _get("brands.json")
if params.response_format == ResponseFormat.JSON:
return json.dumps(data, indent=2, default=str)
return "\n".join([f"- **#{brand['id']}** {brand.get('name')}" for brand in data.get("brands", [])])
except Exception as e:
return _handle_error(e)
```
新工具除非客户端明确批准写入操作，否则均为只读。
## 示例提示
```text
搜索所有带有 rma 标签的打开工单。
```
```text
显示分配给 1 级的工单的完整触发器。
```
```text
列出当前在升级视图中的工单。
```
```text
查找具有 example.com 电子邮件地址的用户。
```
## 打包
此启动存储库旨在公开且免费。付费配套包可以添加安全的写入工具或类型化的自定义端点。安装支持是为想要帮助配置 Claude Desktop、Cursor、自定义应用程序或私有服务器的团队提供的单独附加组件。在共享截图、分叉或客户端特定分支之前：
