Zendesk MCP Server

Zendesk MCP服务器

一个模型上下文协议（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.com

Claude桌面设置

添加到您的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协议。

🛠️ 可用工具

💬 使用示例

配置后，您可以与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令牌

1. 登录您的Zendesk帐户
2. 首选 管理中心 → 应用程序和集成 → 应用程序编程接口 → 中国API
3. 点击 添加API令牌
4. 添加说明：“MCP服务器集成”
5. 点击 创建 并复制令牌
6. 重要：安全保存此令牌-您将不会再看到它

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"

🤝 贡献

欢迎投稿！请随时提交拉取请求。

开发设置

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

报告问题

发现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社区