Skip to main content

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.

PyPI version Python 3.11+ License: MIT Built with FastMCP Zammad 6.0+ and 7.x

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.

Table of Contents

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.2.2 Current (default dev stack)
7.2.x Compatible
7.1 Tested
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.2.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.2.2 by default. Override with ZAMMAD_VERSION in docker/.env (7.2, 7.1, 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
Zammad Commander (GitHub) LibreChat + MCP + your Zammad — internal admin chat

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 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.
  • Zammad Commander — browser chat UI (LibreChat + this MCP server + your Zammad). No Cursor required; docker compose up for internal admin chat. See Zammad Commander (browser chat UI).
  • Open Ticket AI — on-prem classification, summaries, and reply drafts from your helpdesk setup (groups, priorities, categories). No model training. See the integration guide.

All four can run side by side. MCP is the fastest path to “talk to my helpdesk from Claude.” Want a team chat UI instead of an IDE? Use Zammad Commander. Want classification on your own infrastructure? 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 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

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."

Zammad Commander (browser chat UI)

Not every agent wants Cursor or Claude Desktop. Zammad Commander is the official companion project: Docker Compose bundles LibreChat, this MCP server (Streamable HTTP sidecar), and your Zammad so support leads get a browser chat for search, summaries, and reply drafts (human-in-the-loop — no auto-send, deletes denied by default).

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).

Open http://localhost:3080, pick Zammad Commander, and start chatting.

You need Where
Full setup (OpenRouter vs Ollama, demo Zammad, hardware) Commander README
Step-by-step from the MCP side docs/ZAMMAD_COMMANDER.md
MCP env / deny lists Commander uses Configuration guide

Development Environment

We provide a complete Docker Compose setup for local development. Default: Zammad 7.2.2; 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 35 typed MCP tools for Zammad. 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
  • list_ticket_tags / add_ticket_tag / remove_ticket_tag - Ticket tags
  • get_article_attachment - Download an article file
  • link_tickets / merge_tickets - Relate or merge tickets
  • summarize_ticket - Plain-text thread + tags for agents

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
  • create_group - Create a group

Tags (admin catalog)

  • list_tags - Global tag list

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 (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

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

ZAMMAD_HTTP_TOKEN=your_token_here

Create tokens in Zammad: Profile → Token Access

2. OAuth2

ZAMMAD_OAUTH2_TOKEN is a bearer token. Obtain one with a browser login (the callback must be registered on a Zammad OAuth application under Admin → System → API):

zammad-mcp-server login --url https://helpdesk.example.com --client-id YOUR_CLIENT_ID

The command listens on http://127.0.0.1:8765/callback, then prints ZAMMAD_OAUTH2_TOKEN=.... Paste that into the MCP client env. A token you already hold can be set directly:

ZAMMAD_OAUTH2_TOKEN=your_oauth_token

Personal access tokens stay on ZAMMAD_HTTP_TOKEN (Authorization: Token token=...). See Zammad API authentication.

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
  • zammad://config/priorities - Available priorities
  • zammad://organization/{id} - Organization snapshot

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
  • analyze_ticket - Structured analysis with tags and SLA hints
  • draft_response - Locale-aware customer or internal reply
  • triage_queue - Prioritize open tickets in a group
  • escalation_summary - Overdue / pending-close briefing

Hosting options

The Zammad MCP Server can be hosted in multiple ways:

1. Local Development

zammad-mcp-server

2. Docker Container

Published images are on GitHub Container Registry (ghcr.io):

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

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

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

Build locally:

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.2.2 (current dev stack), 7.1 and 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'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).

What is Zammad Commander?

Zammad Commander is a separate MIT project: LibreChat + this MCP server + your Zammad in one docker compose up. Use it when support leads need a browser chat UI instead of Claude Desktop or Cursor. Setup: docs/ZAMMAD_COMMANDER.md.

Contributing

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

Development Workflow

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

Roadmap

  • WebSocket support for real-time updates
  • Ticket subscription and notification system
  • Advanced search with Elasticsearch integration
  • Multi-tenant support
  • Audit logging
  • Custom tool plugins
  • GraphQL API support
  • Webhook integration

License

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

Support

Acknowledgments


Made with ❤️ by Open Ticket AI

Metadata

Release files for zammad-mcp-server 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zammad-mcp-server 0.2.2
File Size Uploaded Provenance Actions
zammad_mcp_server-0.2.2.tar.gz 7.5 MB Without provenance Details for zammad_mcp_server-0.2.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zammad-mcp-server 0.2.2
File Interpreter ABI Platform Actions
zammad_mcp_server-0.2.2-py3-none-any.whl Python 3 none any Details for zammad_mcp_server-0.2.2-py3-none-any.whl

Total release size: 7.5 MB

Release files / zammad_mcp_server-0.2.2.tar.gz

Download URL zammad_mcp_server-0.2.2.tar.gz
Size 7.5 MB
Tags Source
SHA-256 checksum
How to use checksums
95e020ce2e22a39ec3c45848109eee56113fc43523446e4ea1ce995867107b44
BLAKE2b-256 checksum
How to use checksums
f6e93d252b88135d565d2c928bd883294dec71f1208bb90d2d1f66d2f9e409d9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.22

Release files / zammad_mcp_server-0.2.2-py3-none-any.whl

Download URL zammad_mcp_server-0.2.2-py3-none-any.whl
Size 36.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce6e7568950136a6dfbd906fd0181823ec98fe4549808f7dce5d330e5ccf8fb0
BLAKE2b-256 checksum
How to use checksums
288789b9e91b16612896c9103a88e7206b9df36dc6b71d0306d51171b632e733
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.8.22

Security for zammad-mcp-server 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page