Zammad MCP Server — Connect Claude, Cursor & LLMs to Your Zammad Helpdesk

Zammad MCP Server is a free, open-source, production-ready Model Context Protocol (MCP) server for Zammad, the open-source helpdesk and ticket system. It connects AI assistants — Claude Desktop, Cursor, and any MCP-compatible LLM agent — directly to your Zammad instance, so you can search tickets, summarize threads, draft replies, and manage users and organizations in natural language.

In one line: uvx zammad-mcp-server turns your Zammad helpdesk into a set of typed tools any AI agent can call — no Zammad plugin, no custom REST glue code.

⭐ Find this useful? Star the repo — it helps other Zammad teams discover the project and shapes the roadmap.

Overview

The Zammad MCP Server gives AI assistants like Claude structured, type-safe access to Zammad ticket system functionality over the Model Context Protocol — an open standard for connecting LLMs to external tools and data. Instead of scraping the UI or pasting ticket text into a chat window, the assistant calls discrete, validated tools (search_tickets, get_ticket_articles, create_article, and 30+ more) and gets clean, schema-checked data back.

This enables AI-powered ticket management, customer-support automation, and helpdesk reporting through natural-language interactions — while keeping your data on your Zammad instance and your MCP client.

Why use the Zammad MCP Server?

Connecting a large language model to a real helpdesk usually means writing a bespoke Zammad REST integration, handling authentication, and reinventing access control before you get a single useful answer. This server removes that friction:

Talk to your helpdesk from Claude or Cursor — "Summarize ticket 4821", "List open tickets in the Support queue", "Draft a reply to this customer."
Triage and reporting — let an agent classify, prioritize, and summarize incoming tickets, or pull get_ticket_stats for analytics.
Safe by default — granular, environment-driven access control lets you ship read-only or deny destructive tools (delete_ticket, delete_user) in production.
One integration, every client — write to MCP once and it works across Claude Desktop, Cursor, and custom agent stacks.
No vendor lock-in — MIT-licensed, self-hosted, and works with any Zammad 6.0+ / 7.x instance via the REST API (no Zammad-side plugin required).

Key features

Comprehensive API Coverage: Full access to tickets, users, organizations, groups, and more
Advanced Access Control: Granular permissions with category-based and tool-level restrictions
Production-Ready: Built with FastMCP, Pydantic, and modern Python practices
Flexible Authentication: Supports API tokens, OAuth2, and basic authentication
Smart Caching: Intelligent caching for static data (groups, states, priorities)
Type-Safe: Full Pydantic models with runtime validation
Extensible: Easy to add new tools and integrations
Well-Tested: Comprehensive test suite with 90%+ coverage

Zammad compatibility

The MCP server talks to Zammad through the REST API. No Zammad-side plugin is required. Full matrix: docs/COMPATIBILITY.md.

Zammad version	Status
7.1	Tested (primary; default dev stack)
7.0	Tested
6.5.x	Compatible
6.0 – 6.4.x	Compatible (minimum supported line)
< 6.0	Not supported

MCP package vs Zammad: zammad-mcp-server on PyPI is versioned independently (0.1.x). One MCP release works with every supported Zammad version — set ZAMMAD_URL to your instance; no per-Zammad MCP build.

Local dev stack: docker/ ships Zammad 7.1 by default. Override with ZAMMAD_VERSION in docker/.env (7.0, 6.5, 6.3 also supported). See docker/README.md.

Zammad 7.x requires PostgreSQL on the Zammad side (MySQL is not supported from 7.0 onward). The bundled dev stack uses PostgreSQL.

Documentation

Full guides, security checklists, and deployment notes live on the Open Ticket AI website:

Page	What you will learn
Zammad MCP Server (overview)	Who it is for and how it fits the Zammad + AI landscape
Quick Start	Install and run `health_check` in minutes
Claude & Cursor Setup	MCP client configuration
Configuration	Environment variables and access policies
Tools Reference	All MCP tools by category
Security	Tokens, least privilege, production checklist
Deployment	Docker, SSE, and production notes
Zammad compatibility (GitHub)	Supported Zammad versions and dev-stack tags

Tutorial: Zammad MCP Server — setup and usage (blog)

Deutsch: Zammad MCP Server Dokumentation · Einrichtung und Nutzung (Blog)

How this fits the Zammad + AI landscape

Zammad 7.1 native AI — built-in summaries and writing assistant inside the Zammad UI.
Zammad MCP Server (this project) — connects external MCP clients (Claude Desktop, Cursor, custom agents) to Zammad.
Open Ticket AI Runtime — on-prem inference with custom-trained models via the OTAI Zammad connector (integration guide).

All three can coexist. MCP is the fastest path to “talk to my helpdesk from Claude.” Need custom models on your queues? See Open Ticket AI for Zammad.

Quick Start

Step-by-step walkthrough: Quick Start guide

Installation

From PyPI (recommended for MCP clients):

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

From source (development):

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

Configuration

See the Configuration guide for all environment variables and access policies.

Create a .env file:

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

Running the Server

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

# Run with SSE transport (for remote clients)
zammad-mcp-server --transport sse --port 8000

Claude Desktop / Cursor

Full client setup: Claude & Cursor Setup

Add to claude_desktop_config.json or Cursor Settings → 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"
      }
    }
  }
}

Restart the app after saving. Ask: "Run health_check on Zammad" or "List open tickets."

Development Environment

We provide a complete Docker Compose setup for local development. Default: Zammad 7.1; set ZAMMAD_VERSION in docker/.env for other supported tags — see 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: admin@example.com / admin

Running Tests

# 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

Available MCP tools

The server provides 30+ MCP tools for Zammad, organized into categories. Full reference: Tools Reference

Tickets

get_ticket - Get ticket details
search_tickets - Search with filters
create_ticket - Create new tickets
update_ticket - Update ticket properties
delete_ticket - Delete tickets (admin)
get_ticket_articles - Get all messages
create_article - Add responses/notes
get_ticket_stats - Analytics and metrics
get_ticket_states - List available states
get_priorities - List priority levels

Users

get_user - Get user details
search_users - Find users
create_user - Add new users
update_user - Modify user properties
delete_user - Remove users (admin)
get_current_user - Get authenticated user

Organizations

get_organization - Get organization details
search_organizations - Find organizations
create_organization - Add organizations
update_organization - Modify organizations
delete_organization - Remove organizations (admin)

Groups

get_group - Get group details
list_groups - List all groups

System

health_check - Check server health
get_server_info - Get Zammad version/info
get_allowed_tools - List accessible tools

Access control & security

The server includes a sophisticated access control system so you can safely connect AI agents to production Zammad. Production checklist: Security guide

Permission Levels

DENIED - Tool completely inaccessible
READ_ONLY - Can view but not modify
WRITE - Can read and modify data
ADMIN - Full access including deletion

Configuration via Environment Variables

# 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
MCP_ALLOWED_GROUPS=Support,Sales

Programmatic Access Control

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

See ARCHITECTURE.md for detailed technical documentation.

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

Authentication Methods

The server supports three authentication methods. Details: Configuration — authentication

1. API Token (Recommended)

ZAMMAD_HTTP_TOKEN=your_token_here

Create tokens in Zammad: Profile → Token Access

2. OAuth2 Token

ZAMMAD_OAUTH2_TOKEN=your_oauth_token

3. Username/Password

ZAMMAD_USERNAME=admin@example.com
ZAMMAD_PASSWORD=your_password

Resources

The server exposes several MCP resources:

zammad://ticket/{id} - Formatted ticket with articles
zammad://user/{id} - User details
zammad://config/states - Available ticket states

Prompts

Built-in prompts for common workflows:

ticket_summary_prompt - Generate ticket summaries
customer_communication_prompt - Draft customer responses
escalation_analysis_prompt - Analyze escalation needs

Hosting options

The Zammad MCP Server can be hosted in multiple ways:

1. Local Development

zammad-mcp-server

2. Docker Container

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

3. Cloud Deployment

See the Deployment guide for Docker, SSE, and production hosting (Google Cloud Run, Railway, Fly.io, and more).

FAQ

What is the Zammad MCP Server?

It is an open-source Model Context Protocol server that exposes your Zammad helpdesk as typed tools for AI assistants. Any MCP client (Claude Desktop, Cursor, or a custom agent) can then read and act on Zammad tickets, users, and organizations in natural language.

How do I connect Claude or Cursor to Zammad?

Install the package and add it to your MCP client config with ZAMMAD_URL and ZAMMAD_HTTP_TOKEN. The fastest path is uvx zammad-mcp-server — see Quick start and the Claude & Cursor setup guide.

Which Zammad versions are supported?

Zammad 7.1 (primary, tested), 7.0 (tested), and 6.0–6.5.x (compatible). It talks to Zammad over the REST API, so no Zammad-side plugin is required. See the compatibility matrix.

Is it safe to use on a production Zammad instance?

Yes. Access is controlled by environment variables — restrict categories (MCP_ALLOWED_CATEGORIES), deny destructive tools (MCP_DENIED_TOOLS=delete_ticket,delete_user), or run fully read-only. Follow the Security guide before going live.

Is the Zammad MCP Server free and open source?

Yes — it is MIT-licensed and free to self-host. There is no SaaS dependency; your ticket data stays on your Zammad instance and your MCP client.

How is this different from Zammad's built-in AI?

Zammad 7.1's native AI adds summaries and a writing assistant inside the Zammad UI. The Zammad MCP Server instead connects external AI agents to Zammad. See how it fits the Zammad + AI landscape.

Can I run it with Docker?

Yes — see Hosting options and the Deployment guide for Docker, SSE, and cloud hosting (Cloud Run, Railway, Fly.io).

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (pytest)
Commit (git commit -m 'Add amazing feature')
Push (git push origin feature/amazing-feature)
Open a Pull Request

Roadmap

License

This project is licensed under the MIT License - see LICENSE for details.

Support

📖 Documentation (EN) · Dokumentation (DE)
📘 Setup tutorial (blog)
🐛 Issue Tracker
💬 Discussions

Acknowledgments

Built with FastMCP by James Lowin
Inspired by the Model Context Protocol
Zammad - The amazing open-source helpdesk

Related Projects

Zammad - The ticket system itself
zammad-py - Python client library

Made with ❤️ by Open Ticket AI

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github/workflows		.github/workflows
docker		docker
docs		docs
src/zammad_mcp_server		src/zammad_mcp_server
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
mcp-publisher.exe		mcp-publisher.exe
pyproject.toml		pyproject.toml
server.json		server.json
uv.lock		uv.lock

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Zammad MCP Server — Connect Claude, Cursor & LLMs to Your Zammad Helpdesk

Table of Contents

Overview

Why use the Zammad MCP Server?

Key features

Zammad compatibility

Documentation

How this fits the Zammad + AI landscape

Quick Start

Installation

Configuration

Running the Server

Claude Desktop / Cursor

Development Environment

Running Tests

Available MCP tools

Tickets

Users

Organizations

Groups

System

Access control & security

Permission Levels

Configuration via Environment Variables

Programmatic Access Control

Architecture

Authentication Methods

1. API Token (Recommended)

2. OAuth2 Token

3. Username/Password

Resources

Prompts

Hosting options

1. Local Development

2. Docker Container

3. Cloud Deployment

FAQ

What is the Zammad MCP Server?

How do I connect Claude or Cursor to Zammad?

Which Zammad versions are supported?

Is it safe to use on a production Zammad instance?

Is the Zammad MCP Server free and open source?

How is this different from Zammad's built-in AI?

Can I run it with Docker?

Contributing

Development Workflow

Roadmap

License

Support

Acknowledgments

Related Projects

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages