Zammad Mcp Server

Name: Zammad Mcp Server
Author: Softoft-Orga

本地服务

github.com/Softoft-Orga商业与营销53 周前更新

代码仓库

关于 Zammad Mcp Server

Zammad MCP Server 将 Zammad 工单系统通过 MCP 接入 Claude、Cursor 等客户端，供支持团队以自然语言查询和管理工单及相关数据。它通过类型化工具提供 REST API 访问，并可按工具和类别配置访问权限。

主要功能

01访问工单、用户、组织和群组
02搜索工单并查看对话
03创建和更新工单及回复
04按类别和工具控制权限
05支持 API 令牌、OAuth2 和基本认证
06缓存静态系统数据

适用场景

01汇总工单对话并起草回复
02筛选待处理工单并进行分诊
03查询工单统计以辅助报告

MCP 相关

该 MCP 服务通过 Zammad REST API 向 MCP 客户端提供工单、用户、组织、群组和系统信息等类型化工具。支持 stdio、Streamable HTTP 和 SSE 传输，并提供可配置的访问控制。

#mcp #zammad #helpdesk #tickets #customer-support #ai-agents #claude #cursor #python #fastmcp

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "zammad": {
      "command": "uvx",
      "args": [
        "zammad-mcp-server"
      ],
      "env": {
        "ZAMMAD_URL": "<ZAMMAD_URL>",
        "ZAMMAD_HTTP_TOKEN": "<ZAMMAD_HTTP_TOKEN>",
        "MCP_DENIED_TOOLS": "<MCP_DENIED_TOOLS>"
      }
    }
  }
}

启动命令uvx zammad-mcp-server

需要配置的环境变量

ZAMMAD_URL

ZAMMAD_HTTP_TOKEN密钥

MCP_DENIED_TOOLS

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypizammad-mcp-serverstdio

工具

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

Zammad MCP 服务 — 将 Claude、Cursor 和大模型连接到你的 Zammad 帮助台

Zammad MCP 服务 是一个免费、开源、可用于生产环境的 Zammad 模型上下文协议（MCP）服务，适用于这款开源帮助台和工单系统。它可将 AI 助手 — Claude Desktop、Cursor 以及任何兼容 MCP 的 LLM Agent — 直接连接到你的 Zammad 实例，让你能用自然语言搜索工单、总结对话、起草回复，以及管理用户和组织。

一句话概括： uvx zammad-mcp-server 可将你的 Zammad 帮助台转换为一组类型化工具，供任何 AI Agent 调用 — 无需 Zammad 插件，也无需自定义 REST 胶水代码。

⭐ 觉得有用？ 给仓库点个 Star — 这有助于其他 Zammad 团队发现此项目，也会影响路线图。

概述

Zammad MCP 服务通过模型上下文协议为 Claude 等 AI 助手提供对 Zammad 工单系统功能的结构化、类型安全访问。模型上下文协议是一种用于将大模型连接到外部工具和数据的开放标准。助手无需抓取界面或将工单文本粘贴到聊天窗口，而是调用独立且经过验证的工具（search_tickets、get_ticket_articles、create_article 等 30 多种工具），并获取整洁、经过架构校验的数据。

这样一来，你便可以通过自然语言交互实现 AI 驱动的工单管理、客户支持自动化和帮助台报告，同时将数据保留在你自己的 Zammad 实例和你自己的 MCP 客户端中。

为什么使用 Zammad MCP 服务？

要将大模型连接到真实的帮助台，通常需要编写专用的 Zammad REST 集成、处理身份验证，并在获得任何有用答案之前重新实现访问控制。本服务消除了这些阻碍：

通过 Claude 或 Cursor 与帮助台对话 — “总结工单 4821”“列出 Support 队列中的未结工单”“为这位客户起草回复。”
分类与报告 — 让 Agent 对收到的工单进行分类、确定优先级并生成摘要，或调用 get_ticket_stats 获取分析数据。
默认安全 — 通过细粒度、由环境变量驱动的访问控制，可在生产环境中启用只读访问，或禁用破坏性工具（delete_ticket、delete_user）。
一次集成，适用于所有客户端 — 只需集成一次 MCP，即可用于 Claude Desktop、Cursor 和自定义 Agent 技术栈。
不受供应商锁定 — 采用 MIT 许可证、可自托管，并可通过 REST API 适配任何 Zammad 6.0+ / 7.x 实例（无需在 Zammad 端安装插件）。

主要功能

全面的 API 覆盖：可全面访问工单、用户、组织、群组等
高级访问控制：通过基于类别和工具级别的限制，实现精细化权限管理
适用于生产环境：采用 FastMCP、Pydantic 和现代 Python 实践构建
灵活的身份验证：支持 API 令牌、OAuth2 和基本身份验证
智能缓存：为静态数据（群组、状态、优先级）提供智能缓存
类型安全：完整的 Pydantic 模型，并支持运行时验证
可扩展：可轻松添加新工具和集成
经过充分测试：全面的测试套件，覆盖率超过 90%

Zammad 兼容性

MCP 服务通过 REST API 与 Zammad 通信。无需在 Zammad 端安装插件。完整兼容性矩阵：docs/COMPATIBILITY.md。

Zammad 版本	状态
7.1	已测试（主要版本；默认开发堆栈）
7.0	已测试
6.5.x	兼容
6.0 – 6.4.x	兼容（最低支持版本线）
< 6.0	不支持

MCP 软件包与 Zammad： PyPI 上的 zammad-mcp-server 使用独立的版本号（0.1.x）。一个 MCP 版本适用于所有受支持的 Zammad 版本——将 ZAMMAD_URL 设置为你的实例即可；无需针对不同 Zammad 版本构建 MCP。

本地开发堆栈： docker/ 默认使用 Zammad 7.1。可在 docker/.env 中通过 ZAMMAD_VERSION 指定其他版本（也支持 7.0、6.5、6.3）。参见 docker/README.md。

Zammad 7.x 要求 Zammad 端使用 PostgreSQL（从 7.0 开始不再支持 MySQL）。附带的开发堆栈使用 PostgreSQL。

文档

完整指南、安全检查清单和部署说明请参阅 Open Ticket AI 网站：

页面	你将了解的内容
Zammad MCP Server（概述）	适用对象，以及它如何融入 Zammad 与 AI 生态
快速入门	几分钟内安装并运行 `health_check`
Claude 与 Cursor 配置	MCP 客户端配置
配置	环境变量和访问策略
工具参考	按类别列出的所有 MCP 工具
安全	令牌、最小权限原则和生产环境检查清单
部署	Docker、SSE 和生产环境说明
Zammad 兼容性（GitHub）	受支持的 Zammad 版本和开发堆栈标签
Zammad Commander（GitHub）	LibreChat + MCP + 你的 Zammad——内部管理聊天

教程： Zammad MCP Server — 设置与使用（博客）

德语： Zammad MCP Server 文档 · 设置与使用（博客）

这如何融入 Zammad + AI 生态

Zammad 7.1 原生 AI — 在 Zammad 界面内置摘要和写作助手。
Zammad MCP Server（本项目） — 将外部 MCP 客户端（Claude Desktop、Cursor、自定义 Agent）连接到 Zammad。
Zammad Commander — 浏览器聊天界面（LibreChat + 本 MCP 服务 + 你的 Zammad）。无需 Cursor；运行 docker compose up 即可启用内部管理聊天。请参阅 Zammad Commander（浏览器聊天界面）。
Open Ticket AI Runtime — 通过 OTAI Zammad 连接器使用定制训练模型进行本地推理（集成指南）。

这三者可以共存。MCP 是“通过 Claude 与我的帮助台对话”最快捷的方式。想要团队聊天界面而不是 IDE？请使用 Zammad Commander。需要在队列中使用定制模型？请参阅适用于 Zammad 的 Open Ticket AI。

快速开始

分步指南：快速开始指南

安装

通过 PyPI 安装（推荐用于 MCP 客户端）：

pip install zammad-mcp-server
# or
uv tool install zammad-mcp-server
# or run once without installing
uvx zammad-mcp-server

从源代码安装（开发）：

git clone https://github.com/Softoft-Orga/zammad-mcp-server.git
cd zammad-mcp-server
uv sync --extra dev

配置

所有环境变量和访问策略请参阅配置指南。

创建 .env 文件：

ZAMMAD_URL=https://your-zammad-instance.com
ZAMMAD_HTTP_TOKEN=your_api_token_here

# Optional: Access control
MCP_ALLOWED_CATEGORIES=all
MCP_DENIED_TOOLS=delete_ticket,delete_user

运行服务

# Run with stdio transport (for Claude Desktop)
zammad-mcp-server

# Run with Streamable HTTP (Docker / remote clients; recommended)
zammad-mcp-server --transport http --host 0.0.0.0 --port 8000

# Legacy SSE transport (older MCP clients)
zammad-mcp-server --transport sse --host 0.0.0.0 --port 8000

Claude Desktop / Cursor

完整的客户端设置说明：Claude 和 Cursor 设置

将其添加到 claude_desktop_config.json 或 Cursor 设置 → MCP：

{
  "mcpServers": {
    "zammad": {
      "command": "uvx",
      "args": ["zammad-mcp-server"],
      "env": {
        "ZAMMAD_URL": "https://your-zammad-instance.com",
        "ZAMMAD_HTTP_TOKEN": "your_token",
        "MCP_DENIED_TOOLS": "delete_ticket,delete_user,delete_organization"
      }
    }
  }
}

保存后重启应用。试着询问：“在 Zammad 上运行 health_check” 或 “列出未结工单。”

Zammad Commander（浏览器聊天界面）

不是每个 Agent 都想使用 Cursor 或 Claude Desktop。Zammad Commander 是官方配套项目：Docker Compose 将 LibreChat、本 MCP 服务 （Streamable HTTP sidecar）和你的 Zammad 打包在一起，让支持主管通过浏览器聊天界面进行搜索、查看摘要和起草回复（人在回路中——不会自动发送，默认禁止删除）。

git clone https://github.com/Softoft-Orga/zammad-commander.git
cd zammad-commander
cp env.example .env
# Set ZAMMAD_URL, ZAMMAD_HTTP_TOKEN, and LibreChat secrets.

docker compose up -d
# On-prem LLM: add -f docker-compose.onprem.yml (see Commander README).

打开 **http://localhost:3080**，选择 Zammad Commander，然后开始聊天。

需求	位置
完整设置（OpenRouter 与 Ollama 的选择、演示用 Zammad、硬件）	Commander README
从 MCP 端开始的分步说明	docs/ZAMMAD_COMMANDER.md
Commander 使用的 MCP 环境变量 / 拒绝列表	配置指南

开发环境

我们提供了完整的 Docker Compose 本地开发环境。默认版本为 Zammad 7.1；如需使用其他受支持的标签，可在 docker/.env 中设置 ZAMMAD_VERSION——请参阅 docker/README.md。

cd docker
docker-compose up -d

# Wait for services to start (may take 2-3 minutes)
docker-compose ps

# Access Zammad at http://localhost:8080
# Default credentials: [email protected] / admin

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=zammad_mcp_server --cov-report=html

# Run specific test file
pytest tests/test_models.py -v

可用的 MCP 工具

此服务为 Zammad 提供 35 个带类型的 MCP 工具。完整参考：工具参考

工单

get_ticket - 获取工单详情
search_tickets - 使用筛选条件搜索
create_ticket - 创建新工单
update_ticket - 更新工单属性
delete_ticket - 删除工单（管理员）
get_ticket_articles - 获取所有消息
create_article - 添加回复／备注
get_ticket_stats - 分析与指标
get_ticket_states - 列出可用状态
get_priorities - 列出优先级
list_ticket_tags / add_ticket_tag / remove_ticket_tag - 工单标签
get_article_attachment - 下载文章文件
link_tickets / merge_tickets - 关联或合并工单
summarize_ticket - 为 Agent 提供纯文本对话串和标签

用户

get_user - 获取用户详情
search_users - 查找用户
create_user - 添加新用户
update_user - 修改用户属性
delete_user - 删除用户（管理员）
get_current_user - 获取已验证身份的用户

组织

get_organization - 获取组织详情
search_organizations - 查找组织
create_organization - 添加组织
update_organization - 修改组织
delete_organization - 删除组织（管理员）

群组

get_group - 获取群组详情
list_groups - 列出所有群组
create_group - 创建群组

标签（管理员目录）

list_tags - 全局标签列表

系统

health_check - 检查服务健康状况
get_server_info - 获取 Zammad 版本／信息
get_allowed_tools - 列出可访问的工具

访问控制与安全

此服务包含一套完善的访问控制系统，让你能够安全地将 AI Agent 连接到生产环境中的 Zammad。生产环境检查清单：安全指南

权限级别

DENIED - 完全无法访问工具
READ_ONLY - 可以查看，但无法修改
WRITE - 可以读取和修改数据
ADMIN - 完全访问权限，包括删除

通过环境变量配置

# Allow all categories (default)
MCP_ALLOWED_CATEGORIES=all

# Allow specific categories only
MCP_ALLOWED_CATEGORIES=tickets,groups,system

# Deny specific dangerous tools
MCP_DENIED_TOOLS=delete_ticket,delete_user,delete_organization

# Restrict to specific groups (reads and writes)
MCP_ALLOWED_GROUPS=Support,Sales

# Restrict to organization IDs
MCP_ALLOWED_ORGANIZATIONS=1,2

# Read-only preset (no creates/updates/deletes)
MCP_DEFAULT_PERMISSION=read_only

# Rate limit (0 disables)
MCP_RATE_LIMIT_PER_MINUTE=60

以编程方式进行访问控制

from zammad_mcp_server.access_control import AccessController, AccessPolicy, Permission, ToolCategory

# Create custom policy
policy = AccessPolicy(
    default_permission=Permission.READ_ONLY,
    category_permissions={
        ToolCategory.TICKETS: Permission.WRITE,
        ToolCategory.ADMIN: Permission.DENIED,
    },
    denied_tools={"delete_ticket"},
)

controller = AccessController(policy)

架构

详细技术文档请参阅 ARCHITECTURE.md。

┌─────────────────┐     ┌─────────────────┐
│  Claude/AI      │     │  MCP Client     │
│  Assistant      │────▶│  (Claude App)   │
└─────────────────┘     └────────┬────────┘
                                 │ MCP Protocol
                        ┌────────▼────────┐
                        │   MCP Server    │
                        │  (FastMCP)      │
                        ├─────────────────┤
                        │  Access Control │
                        │  Tools          │
                        │  Resources      │
                        └────────┬────────┘
                                 │ HTTP/REST
                        ┌────────▼────────┐
                        │  Zammad Client  │
                        │  Wrapper        │
                        └────────┬────────┘
                                 │
                        ┌────────▼────────┐
                        │  Zammad API     │
                        │   Instance      │
                        └─────────────────┘

身份验证方式

此服务支持三种身份验证方式。详情请参阅：配置 — 身份验证

1. API 令牌（推荐）

ZAMMAD_HTTP_TOKEN=your_token_here

在 Zammad 中创建令牌：个人资料 → 令牌访问

2. OAuth2 令牌

ZAMMAD_OAUTH2_TOKEN=your_oauth_token

3. 用户名／密码

[email protected]
ZAMMAD_PASSWORD=your_password

资源

此服务提供多种 MCP 资源：

zammad://ticket/{id} - 包含文章的格式化工单
zammad://user/{id} - 用户详情
zammad://config/states - 可用工单状态
zammad://config/priorities - 可用优先级
zammad://organization/{id} - 组织快照

提示词

为常见工作流内置的提示词：

ticket_summary_prompt - 生成工单摘要
customer_communication_prompt - 起草客户回复
escalation_analysis_prompt - 分析升级需求
analyze_ticket - 带标签和 SLA 提示的结构化分析
draft_response - 根据区域设置起草客户或内部回复
triage_queue - 对群组中的未结工单进行优先级排序
escalation_summary - 逾期／待关闭情况简报

托管选项

Zammad MCP Server 可以通过多种方式托管：

1. 本地开发

zammad-mcp-server

2. Docker 容器

已发布的镜像位于 GitHub Container Registry（ghcr.io）：

docker pull ghcr.io/softoft-orga/zammad-mcp-server:latest

docker run -p 8000:8000 \
  -e ZAMMAD_URL=https://your-zammad.com \
  -e ZAMMAD_HTTP_TOKEN=your_token \
  ghcr.io/softoft-orga/zammad-mcp-server:latest

# Override to legacy SSE if needed:
# docker run ... ghcr.io/softoft-orga/zammad-mcp-server:latest \
#   zammad-mcp-server --transport sse --host 0.0.0.0 --port 8000

本地构建：

docker build -t zammad-mcp-server .
docker run -p 8000:8000 -e ZAMMAD_URL=$ZAMMAD_URL zammad-mcp-server

3. 云部署

请参阅部署指南，了解 Docker、SSE 和生产环境托管（Google Cloud Run、Railway、Fly.io 等）。

常见问题

什么是 Zammad MCP Server？

这是一个开源的 Model Context Protocol 服务，可将你的 Zammad 服务台作为类型化工具提供给 AI 助手。任何 MCP 客户端（Claude Desktop、Cursor 或自定义 Agent）随后都可以通过自然语言读取和操作 Zammad 工单、用户和组织。

如何将 Claude 或 Cursor 连接到 Zammad？

安装软件包，并在 MCP 客户端配置中添加它，同时设置 ZAMMAD_URL 和 ZAMMAD_HTTP_TOKEN。最快的方式是运行 uvx zammad-mcp-server——请参阅快速入门和 Claude 与 Cursor 设置指南。

支持哪些 Zammad 版本？

支持 Zammad 7.1（主要版本，已测试）、7.0（已测试）和 6.0–6.5.x（兼容）。它通过 REST API 与 Zammad 通信，因此无需在 Zammad 端安装插件。请参阅兼容性矩阵。

在生产环境的 Zammad 实例上使用安全吗？

安全。访问由环境变量控制——限制类别（MCP_ALLOWED_CATEGORIES）、禁用破坏性工具（MCP_DENIED_TOOLS=delete_ticket,delete_user），或将其设为完全只读。正式上线前，请遵循安全指南。

Zammad MCP Server 是否免费且开源？

是的——它采用 MIT 许可证，可免费自托管。它不依赖 SaaS；你的工单数据会保留在 Zammad 实例和 MCP 客户端中。

这与 Zammad 内置的 AI 有何不同？

Zammad 7.1 的原生 AI 会在 Zammad 界面中提供摘要和写作助手。而 Zammad MCP Server 则将外部 AI Agent 连接到 Zammad。请参阅它在 Zammad + AI 生态中的定位。

可以通过 Docker 运行吗？

可以——请参阅托管选项和部署指南，了解 Docker、SSE 和云托管（Cloud Run、Railway、Fly.io）。

什么是 Zammad Commander？

Zammad Commander 是一个独立的 MIT 项目：通过一次 docker compose up，即可将 LibreChat、本 MCP 服务和你的 Zammad 组合在一起。当支持主管需要使用浏览器聊天界面，而不是 Claude Desktop 或 Cursor 时，可使用它。设置说明： docs/ZAMMAD_COMMANDER.md。

参与贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

开发工作流

Fork 此仓库
创建功能分支（git checkout -b feature/amazing-feature）
进行更改
运行测试（pytest）
提交（git commit -m 'Add amazing feature'）
推送（git push origin feature/amazing-feature）
创建 Pull Request

路线图

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE。

支持

致谢

使用 James Lowin 开发的 FastMCP 构建
受 Model Context Protocol 启发
Zammad——出色的开源服务台

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Zammad Mcp Server

关于 Zammad Mcp Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

Zammad MCP 服务 — 将 Claude、Cursor 和大模型连接到你的 Zammad 帮助台

目录

概述

为什么使用 Zammad MCP 服务？

主要功能

Zammad 兼容性

文档

这如何融入 Zammad + AI 生态

快速开始

安装

配置

运行服务

Claude Desktop / Cursor

Zammad Commander（浏览器聊天界面）

开发环境

运行测试

可用的 MCP 工具

工单

用户

组织

群组

标签（管理员目录）

系统

访问控制与安全

权限级别

通过环境变量配置

以编程方式进行访问控制

架构

身份验证方式

1. API 令牌（推荐）

2. OAuth2 令牌

3. 用户名／密码

资源

提示词

托管选项

1. 本地开发

2. Docker 容器

3. 云部署

常见问题

什么是 Zammad MCP Server？

如何将 Claude 或 Cursor 连接到 Zammad？

支持哪些 Zammad 版本？

在生产环境的 Zammad 实例上使用安全吗？

Zammad MCP Server 是否免费且开源？

这与 Zammad 内置的 AI 有何不同？

可以通过 Docker 运行吗？

什么是 Zammad Commander？

参与贡献

开发工作流

路线图

许可证

支持

致谢

相关项目

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？