使用说明

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协议。

🛠️ 可用工具

工具	说明	示例用法
`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 updated<2024-01-31

# Tag searches
tags:billing tags:technical-issue

# Requester searches
requester:customer@company.com

# 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"

🤝 贡献

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

开发设置

分叉存储库
创建功能分支(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/

🆘 支持

问题: GitHub问题
中国API: Zendesk开发人员文档
MCP协议: MCP文件

由以下材料制成❤️ 面向MCP和Zendesk社区