Zendesk MCP服务器
](https://www.npmjs.com/package/zd-mcp-server) 
一个模型上下文协议（MCP）服务器，为Claude等AI助手提供与Zendesk Support的无缝集成。支持与Zendesk票证的自然语言交互，允许您通过对话式AI搜索、创建、更新和管理支持票证。
✨ 特性
- 🎫 完整的票务管理：创建、读取、更新和搜索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="your-email@company.com"
export ZENDESK_TOKEN="your-zendesk-api-token"
export ZENDESK_SUBDOMAIN="your-company" # from https://your-company.zendesk.comClaude桌面设置
添加到您的Claude Desktop配置文件中：
地点：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%/Claude/claude_desktop_config.json
配置：
{
"mcpServers": {
"zendesk": {
"command": "npx",
"args": ["-y", "zd-mcp-server"],
"env": {
"ZENDESK_EMAIL": "your-email@company.com",
"ZENDESK_TOKEN": "your-zendesk-api-token",
"ZENDESK_SUBDOMAIN": "your-company"
}
}
}
}替代方案（如果全局安装）：
{
"mcpServers": {
"zendesk": {
"command": "zd-mcp-server",
"env": {
"ZENDESK_EMAIL": "your-email@company.com",
"ZENDESK_TOKEN": "your-zendesk-api-token",
"ZENDESK_SUBDOMAIN": "your-company"
}
}
}
}光标IDE设置
增添 ~/.cursor/mcp.json 或 .cursor/mcp.json 在您的项目中：
{
"mcpServers": {
"zendesk": {
"command": "npx",
"args": ["-y", "zd-mcp-server"],
"env": {
"ZENDESK_EMAIL": "your-email@company.com",
"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 | 添加内部代理人备注 | “添加关于调查进展的私人备注” |
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 john@company.com 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令牌
- 登录您的Zendesk帐户
- 首选 管理中心 → 应用程序和集成 → 应用程序编程接口 → 中国API
- 点击 添加API令牌
- 添加说明：“MCP服务器集成”
- 点击 创建 并复制令牌
- 重要：安全保存此令牌-您将不会再看到它
2.查找您的子域名
您的Zendesk URL格式： https://YOUR-SUBDOMAIN.zendesk.com 使用 YOUR-SUBDOMAIN 随着 ZENDESK_SUBDOMAIN 价值。
3.所需权限
确保您的Zendesk用户帐户具有：
- 代理 角色（最小）
- 门票入场 权限
- 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🔍 故障排除
常见问题
❌ “身份验证失败”错误
- 验证您的API令牌是否正确且尚未过期
- 确保您的电子邮件地址与您的Zendesk帐户匹配
- 检查您的子域拼写是否正确（否
.zendesk.com后缀）
❌ “权限被拒绝”错误
- 验证您的Zendesk用户是否具有代理权限或更高权限
- 确保为您的帐户启用API访问
- 检查您的令牌是否具有所需的范围
❌ “找不到服务器”错误
- 确保您已安装该软件包：
npm install -g zd-mcp-server - 请尝试使用npx：
npx zd-mcp-server - 检查MCP客户端配置文件语法是否正确
❌ “未设置环境变量”错误
- 验证是否已设置所有三个环境变量：
ZENDESK_EMAIL,ZENDESK_TOKEN,ZENDESK_SUBDOMAIN - 设置环境变量后重新启动MCP客户端
- 检查环境变量名称中的拼写错误
调试模式
启用调试日志记录：
DEBUG=zd-mcp-server:* zd-mcp-server日志文件
检查MCP客户端日志：
- 克劳德桌面:
~/Library/Logs/Claude/（macOS）或%APPDATA%/Claude/logs/（Windows） - 光标：检查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 updated2024-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"🤝 贡献
欢迎投稿！请随时提交拉取请求。
开发设置
- 分叉存储库
- 创建功能分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
报告问题
发现bug了吗？请通过以下方式打开问题：
- 问题描述
- 重现步骤
- 预期行为
- 您的环境（操作系统、Node.js版本、MCP客户端）
- 相关日志输出
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🔗 链接
- 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/
- 模型上下文协议: https://modelcontextprotocol.io/
🆘 支持
- 问题:
- 中国API: Zendesk开发人员文档
- MCP协议: MCP文件
______________________________________________________________________
由以下材料制成❤️ 面向MCP和Zendesk社区
