项目简介

Zammad MCP服务器是一个基于Model Context Protocol (MCP)构建的后端服务，旨在将Zammad工单管理系统的功能以标准化的方式暴露给大型语言模型（LLM）客户端。它允许AI助手执行工单管理、用户查询、组织信息获取等操作，从而提升工单处理效率和客户服务自动化水平。

主要功能点

工单管理: 搜索、获取详情、创建、更新工单；添加评论/备注；管理工单标签；支持附件上传和下载。
用户与组织管理: 获取当前用户信息；按ID查询或搜索用户与组织。
系统信息: 获取Zammad系统中的所有群组、工单状态和优先级列表；获取工单统计数据。
资源访问: 通过URI直接访问特定工单、用户、组织和群组的详细信息，例如 'zammad://ticket/{id}'。
Prompt模板: 提供预配置的Prompt模板，用于工单分析、起草回复和升级工单总结等常见任务，帮助LLM更高效地完成复杂交互。

安装步骤

项目推荐使用 'uvx' 或 Docker 运行。

使用 'uvx' (推荐):

确保您的系统已安装 'uv' (一个快速的Python包管理器)。
- macOS/Linux: 'curl -LsSf https://astral.sh/uv/install.sh | sh'
- Windows (PowerShell): 'powershell -c "irm https://astral.sh/uv/install.ps1 | iex"'

通过环境变量配置Zammad API凭据，然后直接运行：

ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \
ZAMMAD_HTTP_TOKEN=your-api-token \
uvx --from git+https://github.com/basher83/Zammad-MCP.git mcp-zammad

使用 Docker:

通过环境变量配置Zammad API凭据，然后运行Docker容器：

docker run --rm -i \
  -e ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \
  -e ZAMMAD_HTTP_TOKEN=your-api-token \
  ghcr.io/basher83/zammad-mcp:latest

为了更好的安全性，可以使用Docker secrets或 '.env' 文件。

服务器配置

MCP客户端需要配置MCP服务器的启动命令和相关参数。以下是基于仓库信息生成的JSON配置示例，适用于不同的MCP客户端（如Claude Desktop）：

使用 'uvx' 运行:

{
  "zammad": {
    "command": "uvx",
    "args": ["--from", "git+https://github.com/basher83/zammad-mcp.git", "mcp-zammad"],
    "env": {
      "ZAMMAD_URL": "https://your-instance.zammad.com/api/v1",
      "ZAMMAD_HTTP_TOKEN": "your-api-token"
    }
  }
}

'"zammad"': MCP服务器的名称，客户端将用此名称引用此服务器。
'"command"': 启动MCP服务器的执行命令，此处为 'uvx'。
'"args"': 传递给 'uvx' 命令的参数，指定从GitHub仓库运行 'mcp-zammad'。
'"env"': 环境变量的键值对，用于配置Zammad API的URL和认证令牌。请将 'https://your-instance.zammad.com/api/v1' 和 'your-api-token' 替换为您的实际Zammad实例URL和API令牌。

使用 Docker 运行:

{
  "zammad": {
    "command": "docker",
    "args": [
      "run", "--rm", "-i",
      "-e", "ZAMMAD_URL=https://your-instance.zammad.com/api/v1",
      "-e", "ZAMMAD_HTTP_TOKEN=your-api-token",
      "ghcr.io/basher83/zammad-mcp:latest"
    ]
  }
}

'"zammad"': MCP服务器的名称，客户端将用此名称引用此服务器。
'"command"': 启动MCP服务器的执行命令，此处为 'docker'。
'"args"': 传递给 'docker run' 命令的参数，包括必要的 '-e' 环境变量（Zammad URL和API令牌）以及Docker镜像名称 'ghcr.io/basher83/zammad-mcp:latest'。请将 'https://your-instance.zammad.com/api/v1' 和 'your-api-token' 替换为您的实际Zammad实例URL和API令牌。
重要提示: 'docker run' 命令中必须包含 '-i' (interactive mode) 标志，以确保MCP服务器能接收标准输入（stdin）进行通信。

基本使用方法

一旦MCP服务器配置并启动，您的LLM客户端即可通过JSON-RPC协议与之通信，调用其提供的工具、访问资源或请求Prompt模板。

搜索开放工单: 让LLM使用 'zammad_search_tickets' 工具，参数为 'state="open"' 来查找所有开放工单。
创建支持工单: 让LLM使用 'zammad_create_ticket' 工具，提供 'title' (标题)、'group' (群组)、'customer' (客户邮箱或ID) 和 'article_body' (初始消息体) 等参数。
分析工单: 让LLM请求 'analyze_ticket' Prompt，并提供 'ticket_id' (工单ID)。Prompt会引导LLM使用 'zammad_get_ticket' 等工具获取工单详情并进行分析。
下载附件: 让LLM使用 'zammad_download_attachment' 工具，提供 'ticket_id', 'article_id' 和 'attachment_id' 来下载特定工单文章的附件内容（以Base64编码返回）。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息