Zendesk MCP Server

Zendesk MCP 服务

一个模型上下文协议（MCP）服务，可让 Claude 等 AI 助手无缝集成 Zendesk Support。通过对话式 AI，使用自然语言与 Zendesk 工单交互，从而搜索、创建、更新和管理支持工单。

✨ 功能

• 🎫 完整的工单管理：创建、读取、更新和搜索 Zendesk 工单
• 💬 评论和备注：添加公开评论和私密内部备注
• 🔍 高级搜索：使用 Zendesk 强大的查询语法搜索工单
• 🔗 事件管理：检索和管理关联的事件工单
• 🏷️ 标签管理：添加和管理工单标签及元数据
• 🔒 安全认证：使用 Zendesk API 令牌进行安全访问
• 🚀 轻松安装：可通过 npm、npx 或手动设置

🚀 快速开始

选项 1：通过 NPM 安装（推荐）

npm install -g zd-mcp-server

选项 2：通过 npx 使用（无需安装）

npx zd-mcp-server

选项 3：开发环境设置

git clone https://github.com/koundinya/zd-mcp-server.git
cd zd-mcp-server
npm install
npm run build

⚙️ 配置

环境变量

在系统或 MCP 客户端配置中设置以下环境变量：

export ZENDESK_EMAIL="[email protected]"
export ZENDESK_TOKEN="your-zendesk-api-token"
export ZENDESK_SUBDOMAIN="your-company"  # from https://your-company.zendesk.com

Claude Desktop 设置

将以下内容添加到 Claude Desktop 配置文件中：

位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

配置：

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "zd-mcp-server"],
      "env": {
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_TOKEN": "your-zendesk-api-token",
        "ZENDESK_SUBDOMAIN": "your-company"
      }
    }
  }
}

替代方式（如果已全局安装）：

{
  "mcpServers": {
    "zendesk": {
      "command": "zd-mcp-server",
      "env": {
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_TOKEN": "your-zendesk-api-token",
        "ZENDESK_SUBDOMAIN": "your-company"
      }
    }
  }
}

Cursor IDE 设置

将以下内容添加到 ~/.cursor/mcp.json 或项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "zd-mcp-server"],
      "env": {
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_TOKEN": "your-zendesk-api-token",
        "ZENDESK_SUBDOMAIN": "your-company"
      }
    }
  }
}

其他 MCP 客户端

对于其他兼容 MCP 的客户端（Cline、Windsurf 等），请参阅其文档了解 MCP 服务配置。本服务支持标准 MCP 协议。

🛠️ 可用工具

工具	描述	使用示例
zendesk_get_ticket	按 ID 获取工单	“获取工单 #12345”
zendesk_get_ticket_details	获取包含评论的工单详情	“显示工单 #67890 的完整详情”
zendesk_search	使用查询语法搜索工单	“查找上周的所有紧急工单”
zendesk_create_ticket	创建新工单	“为登录问题创建一个高优先级工单”
zendesk_update_ticket	更新工单属性	“将工单 #555 的状态设为已解决”
zendesk_add_private_note	添加内部 Agent 备注	“添加一条关于调查进展的私密备注”
zendesk_add_public_note	添加面向客户的公开评论	“回复客户并提供解决步骤”
zendesk_get_linked_incidents	获取与问题关联的事件工单	“显示与此问题工单相关的事件”

💬 使用示例

配置完成后，你可以使用自然语言与 AI 助手交互：

工单管理

"Show me all high priority tickets assigned to me"
"Create a new ticket: Customer can't access dashboard, priority urgent"
"Update ticket #12345 status to pending and add a note about waiting for customer response"

搜索和发现

"Find all solved tickets from this week tagged with 'billing'"
"Search for open tickets containing 'password reset'"
"Show me tickets created by [email protected] in the last 30 days"

客户沟通

"Add a public comment to ticket #789: 'We've identified the issue and working on a fix'"
"Add a private note: 'Customer confirmed the workaround is effective'"

高级查询

"Find all problem tickets that have linked incidents"
"Show me escalated tickets that haven't been updated in 2 days"
"Get details for ticket #456 including all comments and history"

🔑 身份验证设置

1. 生成 API 令牌

1. 登录 Zendesk 账户
2. 前往 Admin Center → Apps and integrations → APIs → Zendesk API
3. 点击 Add API token
4. 添加描述：“MCP Server Integration”
5. 点击 Create 并复制令牌
6. 重要：请妥善保存此令牌，因为之后将无法再次查看

2. 查找子域名

Zendesk URL 格式：https://YOUR-SUBDOMAIN.zendesk.com 将 YOUR-SUBDOMAIN 用作 ZENDESK_SUBDOMAIN 的值。

3. 所需权限

确保你的 Zendesk 用户账户具备以下权限：

• Agent 角色（最低要求）
• 工单访问权限
• 已启用 API 访问

🔧 开发

项目结构

zd-mcp-server/
├── src/
│   ├── index.ts          # Server entry point
│   └── tools/
│       └── index.ts      # Zendesk tool implementations
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

从源代码构建

git clone https://github.com/koundinya/zd-mcp-server.git
cd zd-mcp-server
npm install
npm run build

本地运行

# Start the server
npm start

# Development mode with auto-rebuild
npm run dev

测试

# Test with MCP Inspector (if available)
npx @modelcontextprotocol/inspector zd-mcp-server

# Or test the built version
npx @modelcontextprotocol/inspector node dist/index.js

🔍 故障排除

常见问题

❌ “Authentication failed” 错误

• 确认 API 令牌正确且未过期
• 确保电子邮件地址与 Zendesk 账户一致
• 检查子域名是否拼写正确（不含 .zendesk.com 后缀）

❌ “Permission denied” 错误

• 确认 Zendesk 用户拥有 Agent 权限或更高权限
• 确保账户已启用 API 访问权限
• 检查令牌是否具有所需的范围

❌ “Server not found” 错误

• 确保已安装此软件包：npm install -g zd-mcp-server
• 尝试改用 npx：npx zd-mcp-server
• 检查 MCP 客户端配置文件的语法是否正确

❌ “Environment variables not set” 错误

• 确认已设置以下三个环境变量：ZENDESK_EMAIL、ZENDESK_TOKEN、ZENDESK_SUBDOMAIN
• 设置环境变量后重启 MCP 客户端
• 检查环境变量名称是否有拼写错误

调试模式

启用调试日志：

DEBUG=zd-mcp-server:* zd-mcp-server

日志文件

查看 MCP 客户端日志：

• Claude Desktop：~/Library/Logs/Claude/（macOS）或 %APPDATA%/Claude/logs/（Windows）
• Cursor：在输出面板中查看 MCP 服务日志
• 终端：直接运行服务以查看实时日志

📚 高级用法

搜索查询语法

Zendesk 搜索支持强大的查询运算符：

# Status-based searches
status:open status:pending status:solved

# Priority searches  
priority:urgent priority:high priority:normal priority:low

# Date-based searches
created>2024-01-01 updated<2024-01-31

# Tag searches
tags:billing tags:technical-issue

# Requester searches
requester:[email protected]

# Complex combinations
status:open priority:high created>2024-01-01 tags:billing

批量操作

虽然此服务不直接支持批量操作，但你可以串联命令：

"Search for all urgent tickets, then show me details for the first 3 results"
"Find tickets tagged 'billing', update them to normal priority, and add a note about the billing system maintenance"

🤝 贡献

欢迎贡献！欢迎提交 Pull Request。

开发环境设置

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 发起 Pull Request

报告问题

发现 Bug？请提交问题，并提供：

• 问题描述
• 重现步骤
• 预期行为
• 你的环境（操作系统、Node.js 版本、MCP 客户端）
• 相关日志输出

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🔗 链接

• GitHub：https://github.com/koundinya/zd-mcp-server
• npm：https://www.npmjs.com/package/zd-mcp-server
• Zendesk API 文档：https://developer.zendesk.com/api-reference/
• Model Context Protocol：https://modelcontextprotocol.io/

🆘 支持

• 问题：GitHub Issues
• Zendesk API：Zendesk 开发者文档
• MCP 协议：MCP 文档

---

为 MCP 和 Zendesk 社区倾心打造 ❤️