zammad-go-mcp

zammad-go-mcp

用于访问 Zammad API 的 MCP 服务。

此服务支持：

• 读取工单和用户列表。
• 获取特定工单和用户的详细信息。
• 搜索工单和用户。
• 创建新工单。
• 向现有工单添加备注（文章）。
• 获取工单的通信历史记录（文章）。

功能

此服务提供以下 MCP 资源和工具：

资源允许 AI 使用 URI 以结构化方式读取 Zammad 中的数据。

• zammad://tickets
  • 名称： 列出工单
  • 描述： 列出配置的 API 令牌可访问的所有工单。
  • MIME 类型： application/json
• zammad://tickets/{ticket_id}（模板）
  • 名称： 显示工单（资源）
  • 描述： 显示由 {ticket_id} 标识的特定工单的详细信息。
  • MIME 类型： application/json
• zammad://users
  • 名称： 列出用户
  • 描述： 列出配置的 API 令牌可访问的所有用户。
  • MIME 类型： application/json
• zammad://users/{user_id}（模板）
  • 名称： 显示用户（资源）
  • 描述： 显示由 {user_id} 标识的特定用户的详细信息。
  • MIME 类型： application/json

工具

工具允许 AI 在 Zammad 中执行操作或特定查询。

• create_ticket：在 Zammad 中创建新工单。
  • 必填：title、group、customer（电子邮件或用户 ID）、body。
  • 可选：type（文章类型，默认值："note"）、internal（布尔值，默认值：false）。
• search_tickets：根据查询字符串搜索工单。
  • 必填：query。
  • 可选：limit（默认值：50）。
• add_note_to_ticket：向现有工单添加内部备注（文章）。
  • 必填：ticket_id、body。
  • 可选：internal（布尔值，默认值：true）。
• get_ticket：根据工单 ID 获取特定工单的详细信息。
  • 必填：ticket_id。
• get_user：根据用户 ID 获取特定用户的详细信息。
  • 必填：user_id。
• search_users：根据查询字符串搜索用户（例如，电子邮件、登录名、姓名）。
  • 必填：query。
  • 可选：limit（默认值：50）。
• get_ticket_articles：获取特定工单的所有文章（通信记录）。
  • 必填：ticket_id。

前置条件

• Go： 已安装 1.24 或更高版本。
• Zammad 实例： 可访问正在运行的 Zammad 实例（URL）。
• Zammad API 令牌： 在 Zammad 实例中生成且具备足够权限的 API 令牌。

获取 Zammad API 令牌

你需要在 Zammad 中生成 API 令牌，以便此 MCP 服务能够进行身份验证并与 API 交互。

1. 使用管理员账户（或有权管理 API 令牌的账户）登录 Zammad 实例。
2. 前往个人资料设置（通常点击左下角的头像或姓名首字母）。
3. 前往令牌访问部分。
4. 点击 "创建" 或相应按钮来生成新令牌。
5. 为令牌设置一个描述性标签（例如，"Claude MCP Server"）。
6. 请务必分配必要的权限。 根据所提供的工具，你可能需要以下权限：
   • ticket.agent（或根据使用场景选择 ticket.customer）——用于查看、创建和搜索工单，以及添加文章。
   • user.reader ——用于查看和搜索用户。
   • （可选） 如果之后添加这些工具，进行更广泛的用户搜索或修改可能需要 admin.user。请查阅 Zammad 的权限文档，了解具体信息。
7. 点击 "创建" 或 "保存"。
8. 立即复制生成的令牌。 Zammad 只会显示一次令牌。请妥善保管。

安装与设置

1. 克隆仓库：

   git clone https://github.com/arush15june/zammad-mcp-go.git
   cd zammad-mcp-go
   

2. 构建二进制文件：

   go build -o zammad-mcp-go main.go
   

   这将在当前目录中创建名为 zammad-mcp-go 的可执行文件（在 Windows 上为 zammad-mcp-go.exe）。

Claude Desktop 配置

{
  "mcpServers": {
        "zammad": {
            "command": "<path-to>/zammad-go-mcp.exe",
            "args": [],
            "env": {
                "ZAMMAD_URL": "<zammad_url>",
                "ZAMMAD_TOKEN": "<zammad_token>"
            }
        }
    }
}