主控服务器

Name: 主控服务器
Author: koundinya

作者：koundinya8 星标更新：2025-06-02

安装使用来源：spider==github.com

项目介绍

Zendesk MCP Server

这是一个模型上下文协议（MCP）服务器，提供与Zendesk支持无缝集成的人工智能助手，如Claude。它允许通过对话式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="your-email@公司.com"
export ZENDESK_TOKEN="您的Zendesk API令牌"
export ZENDESK_SUBDOMAIN="您的公司"  # 来自 https://您的公司.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": "your-email@公司.com",
        "ZENDESK_TOKEN": "您的Zendesk API令牌",
        "ZENDESK_SUBDOMAIN": "您的公司"
      }
    }
  }
}

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

{
  "mcpServers": {
    "zendesk": {
      "command": "zd-mcp-server",
      "env": {
        "ZENDESK_EMAIL": "your-email@公司.com",
        "ZENDESK_TOKEN": "您的Zendesk API令牌",
        "ZENDESK_SUBDOMAIN": "您的公司"
      }
    }
  }
}

Cursor IDE 设置

添加到~/.cursor/mcp.json或项目中的.cursor/mcp.json：

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "zd-mcp-server"],
      "env": {
        "ZENDESK_EMAIL": "your-email@公司.com",
        "ZENDESK_TOKEN": "您的Zendesk API令牌",
        "ZENDESK_SUBDOMAIN": "您的公司"
      }
    }
  }
}

其他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助手进行交互：

票证管理

"显示分配给我的所有高优先级票证"
"创建新票证：客户无法访问仪表盘，紧急优先级"
"更新票证#12345状态为待处理，并添加一条等待客户回复的备注"

搜索与发现

"查找本周标记为'账单'的所有已解决票证"
"搜索包含'密码重置'的开放票证"
"显示过去30天内由john@公司.com创建的票证"

客户沟通

"向票证#789添加公共评论：'我们已经确定了问题，并正在修复'"
"添加私有笔记：'客户确认变通方法有效'"

高级查询

"查找所有具有相关事件的问题票证"
"显示2天内未更新的所有升级票证"
"获取票证#456的详细信息，包括所有评论和历史记录"

🔑 认证设置

1. 生成API令牌

登录您的Zendesk账户
转到管理中心→应用和集成→API→Zendesk API
点击添加API令牌
添加描述："MCP服务器集成"
点击创建并复制令牌
重要：安全保存此令牌——您将不会再看到它

2. 查找您的子域

您的Zendesk网址格式：https://您的子域.zendesk.com 使用您的子域作为ZENDESK_SUBDOMAIN值。

3. 所需权限

确保您的Zendesk用户账户具有：

代理角色（最低）
票证访问权限
API访问已启用

🔧 开发

项目结构

zd-mcp-server/
├── src/
│   ├── index.ts          # 服务器入口点
│   └── tools/
│       └── index.ts      # Zendesk工具实现
├── dist/                 # 编译后的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

本地运行

# 启动服务器
npm start

# 开发模式自动重建
npm run dev

测试

# 使用MCP Inspector测试（如果有）
npx @modelcontextprotocol/inspector zd-mcp-server

# 或测试编译版本
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客户端日志：

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

📚 高级用法

搜索查询语法

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

# 基于状态的搜索
status:open status:pending status:solved

# 基于优先级的搜索
priority:urgent priority:high priority:normal priority:low

# 基于日期的搜索
created>2024-01-01 updated<2024-01-31

# 标签搜索
tags:账单 tags:技术问题

# 请求者搜索
requester:客户@公司.com

# 复合组合
status:open priority:high created>2024-01-01 tags:账单

批量操作

虽然服务器不直接支持批量操作，但可以链式命令：

"搜索所有紧急票证，然后显示前3个结果的详细信息"
"查找标记为'账单'的票证，将其优先级更新为正常，并添加有关账单系统维护的备注"

🤝 贡献

欢迎贡献！请随意提交拉取请求。

开发环境设置

分叉仓库
创建功能分支（git checkout -b feature/惊人的功能）
提交更改（git commit -m '添加惊人的功能'）
推送到分支（git push origin feature/惊人的功能）
打开拉取请求

报告问题

发现错误？请打开一个问题，包括：

问题描述
复现步骤
预期行为
您的环境（操作系统、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/
模型上下文协议：https://modelcontextprotocol.io/

🆘 支持

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

为MCP和Zendesk社区制作，充满❤️