Zammad MCP Server

An MCP server that connects AI assistants to Zammad, providing tools for managing tickets, users, organizations, attachments, and knowledge base content.

Disclaimer: This project is not affiliated with or endorsed by Zammad GmbH or the Zammad Foundation. This is an independent integration that uses the Zammad API.

Features

Tools

• Ticket Management

  • zammad_search_tickets - Search tickets with multiple filters

  • zammad_get_ticket - Get detailed ticket information with articles (supports pagination); custom object attributes are included

  • zammad_create_ticket - Create new tickets

  • zammad_update_ticket - Update ticket properties, including custom object attributes via custom_fields

  • zammad_add_article - Add comments/notes to tickets

  • zammad_merge_tickets - Merge a ticket into another (irreversible)

  • zammad_add_ticket_tag / zammad_remove_ticket_tag - Manage ticket tags

  • zammad_bulk_update_tickets - Update, assign, tag, or close up to 100 tickets in one call with per-ticket failure reporting

  • zammad_get_ticket_tags - Get tags assigned to a specific ticket

  • zammad_list_tags - List all tags defined in the system (requires admin.tag permission)

  • zammad_export_tickets - Export tickets with their conversation articles to a JSONL file on the server host (requires ZAMMAD_EXPORT_DIR; see Ticket Export)

• Attachment Support

  • zammad_get_article_attachments - List attachments for a ticket article

  • zammad_download_attachment - Download attachment content (base64-encoded)

• User & Organization Management

  • zammad_create_user - Create a Zammad user

  • zammad_get_user / zammad_search_users - User information and search

  • zammad_get_organization / zammad_search_organizations - Organization data

  • zammad_get_current_user - Get authenticated user info

• System Information

  • zammad_list_groups - Get all available groups (cached for performance)

  • zammad_list_ticket_states - Get all ticket states (cached for performance)

  • zammad_list_ticket_priorities - Get all priority levels (cached for performance)

  • zammad_get_ticket_stats - Get ticket statistics (optimized with pagination)

• Webhook Events (HTTP transport only)

  • zammad_list_events - Poll ticket events delivered by Zammad webhooks (see Webhook Events)

• Knowledge Base (read-only, requires knowledge_base.reader or knowledge_base.editor permission)

  • zammad_list_knowledge_bases - List all knowledge bases

  • zammad_get_knowledge_base - Get details of one knowledge base by ID

  • zammad_get_kb_category - Get a knowledge base category by ID

  • zammad_list_kb_answers - List answers in a knowledge base category

  • zammad_search_kb_answers - Case-insensitive substring search of answer titles and bodies

  • zammad_get_kb_answer - Get an answer by ID with its resolved title and body

Resources

Access Zammad data directly:

• zammad://ticket/{id} - Individual ticket details

• zammad://user/{id} - User profile information

• zammad://organization/{id} - Organization details

• zammad://queue/{group} - Ticket queue for a group

• zammad://kb/{kb_id} - Knowledge base details

• zammad://kb/{kb_id}/category/{category_id} - Knowledge base category

• zammad://kb/{kb_id}/answer/{answer_id} - Knowledge base answer with title and body

Prompts

Pre-configured prompts:

• analyze_ticket - Comprehensive ticket analysis

• draft_response - Generate ticket responses

• escalation_summary - Summarize escalated tickets

Related MCP server: zammad-mcp

Installation

Option 1: Run Directly with uvx (Recommended)

Run without installation:

# Install uv if you haven't already
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Run directly from GitHub
uvx --from git+https://github.com/basher83/zammad-mcp.git mcp-zammad

# Or with environment variables
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

Option 2: Docker Run

For production or containerized deployments:

# Basic usage with environment variables
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

# If you must skip TLS verification (self-signed / internal CA), add:
#   -e ZAMMAD_INSECURE=true

# Using Docker secrets for better security
docker run --rm -i \
  -e ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \
  -e ZAMMAD_HTTP_TOKEN_FILE=/run/secrets/token \
  -v ./secrets/zammad_http_token.txt:/run/secrets/token:ro \
  ghcr.io/basher83/zammad-mcp:latest

# With .env file
docker run --rm -i \
  --env-file .env \
  ghcr.io/basher83/zammad-mcp:latest

Docker Image Versioning

The project publishes Docker images with semantic versioning:

• latest - Latest successful build from the default branch; may be unstable

• 1.2.3 - Specific version (recommended for production)

• 1.2 - Latest patch of 1.2 minor release

• 1 - Latest minor/patch of 1.x major release

• main - Latest main branch (may be unstable)

# Recommended for production - pin to specific version
docker pull ghcr.io/basher83/zammad-mcp:1.2.0

View all versions on GitHub Container Registry.

Option 3: For Developers

To contribute or modify the code, install mise. mise.toml pins the Python and uv versions and defines the project tasks.

# Clone the repository
git clone https://github.com/basher83/zammad-mcp.git
cd zammad-mcp

# Install the pinned tools from mise.toml (Python, uv, prek, git-cliff, and others)
mise install

# Install the Python dependencies into .venv (uv sync)
mise run setup

# Install the pre-commit hooks
mise run hooks-install

If mise asks you to trust the repository configuration, run mise trust. The Development section below links the contributor guides.

Configuration

The server requires Zammad API credentials. Use a .env file:

1. Copy the example configuration:

   cp .env.example .env

2. Edit .env with your Zammad credentials:

   # Required: Zammad instance URL (include /api/v1)
   ZAMMAD_URL=https://your-instance.zammad.com/api/v1
   
   # Authentication (choose one method):
   # Option 1: API Token (recommended)
   ZAMMAD_HTTP_TOKEN=your-api-token
   
   # Option 2: OAuth2 Token
   # ZAMMAD_OAUTH2_TOKEN=your-oauth2-token
   
   # Option 3: Username/Password
   # ZAMMAD_USERNAME=your-username
   # ZAMMAD_PASSWORD=your-password
   
   # Optional: Disable TLS certificate verification (NOT recommended for production)
   # Truthy values only: 1, true, yes, on. Unset (default) keeps TLS verification enabled.
   # ZAMMAD_INSECURE=true
   
   # Optional: Logging level (default: INFO)
   # Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL
   # LOG_LEVEL=INFO

3. The server will automatically load the .env file on startup.

.env.example lists every optional variable with a comment. The configuration reference documents each variable with its default and allowed values. The optional features are summarized below.

Transport Configuration (Optional)

Audit Logging (Optional)

Audit logging is disabled by default. When ZAMMAD_AUDIT_LOG_ENABLED is set, the server writes one JSON Lines record per tool call, connection attempt, and URL security check to stderr, a file, or syslog, with secrets redacted. See Audit logging for the variables and the record format.

Ticket Export (Optional)

zammad_export_tickets writes a JSON Lines file on the host that runs the MCP server. It is disabled until ZAMMAD_EXPORT_DIR names an existing directory, and every output path must resolve inside that directory. See Ticket export for the variables, filters, and confinement rules.

Important: Keep your .env file out of version control (already in .gitignore).

Response Formats

Tools that return Markdown by default accept a response_format parameter with two values:

• Markdown (default): Human-readable format optimized for LLM consumption

• JSON: Machine-readable format with complete metadata

These are the search, get, and list tools for tickets, users, organizations, groups, states, priorities, tags, and knowledge base content. The write tools, zammad_get_article_attachments, zammad_download_attachment, zammad_get_current_user, zammad_get_ticket_stats, zammad_export_tickets, and zammad_list_events return structured results and have no response_format parameter.

Example:

# Markdown (default)
zammad_search_tickets(query="network", response_format="markdown")

# JSON
zammad_search_tickets(query="network", response_format="json")

Usage

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "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"
      }
    }
  }
}

Or using Docker:

{
  "mcpServers": {
    "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"]
    }
  }
}

Note: The server supports stdio (default) and HTTP transports. Stdio mode requires the -i flag for Docker. See the HTTP Transport section below for remote deployments.

Important: The -i flag is required—without it, the MCP server cannot receive stdin. Preserve this flag in wrapper scripts or shell aliases.

Or if you have it installed locally:

{
  "mcpServers": {
    "zammad": {
      "command": "mcp-zammad",
      "env": {
        "ZAMMAD_URL": "https://your-instance.zammad.com/api/v1",
        "ZAMMAD_HTTP_TOKEN": "your-api-token"
      }
    }
  }
}

Standalone Usage

# Run the server from a repository checkout
uv run mcp-zammad

# Or with environment variables
ZAMMAD_URL=https://instance.zammad.com/api/v1 ZAMMAD_HTTP_TOKEN=token uv run mcp-zammad

HTTP Transport (Remote/Cloud Deployment)

The server supports Streamable HTTP transport for remote deployments. Set MCP_TRANSPORT=http and MCP_PORT. MCP_HOST defaults to 127.0.0.1. The MCP endpoint is /mcp on that host and port.

⚠️ SECURITY WARNING: The server does not implement inbound MCP client authentication. ZAMMAD_* credentials authenticate the server to Zammad, not MCP clients. Bind to 0.0.0.0 only behind an authenticated TLS proxy or inside a network restricted to trusted clients.

The HTTP Transport Deployment Guide covers running with Docker, reverse proxy, systemd, Docker Compose, cloud platforms, client configuration, and security.

Webhook Events (HTTP Transport Only)

Zammad can push ticket events to POST /webhooks/zammad, and MCP clients poll them with zammad_list_events. This needs MCP_TRANSPORT=http and ZAMMAD_WEBHOOK_SECRET. Retention is in memory, bounded to 1000 events, and lost on restart. See Webhook events for the Zammad setup, the status codes, and the polling procedure.

Examples

Search for Open Tickets

Use zammad_search_tickets with state="open" to find all open tickets

Create a Support Ticket

Use zammad_create_ticket with:
- title: "Customer needs help with login"
- group: "Support"
- customer: "customer@example.com"
- article_body: "Customer reported unable to login..."

Update and Respond to a Ticket

1. Use zammad_get_ticket with ticket_id=123 to see the full conversation
2. Use zammad_add_article to add your response
3. Use zammad_update_ticket to change state to "pending reminder" with a pending_time (e.g. "2026-07-01T08:00:00Z")

Analyze Escalated Tickets

Use the escalation_summary prompt to get a report of all tickets approaching escalation

Upload Attachments to a Ticket

Use zammad_add_article with attachments parameter:
- ticket_id: 123
- body: "See attached documentation"
- attachments: [
    {
      "filename": "guide.pdf",
      "data": "JVBERi0xLjQKJ...",  # base64-encoded content
      "mime_type": "application/pdf"
    }
  ]

Merge Duplicate Tickets

Useful for collapsing recurring auto-generated tickets (cron failures, monitoring noise) into one incident. The source ticket's articles move to the target and the source is closed as "merged". This cannot be undone.

Use zammad_merge_tickets with:
- source_ticket_id: 123          # internal ID of the ticket to merge away
- target_ticket_number: "20002"  # display number of the surviving ticket

target_ticket_id may be given instead of target_ticket_number, but not both.

Development

CONTRIBUTING.md covers the development setup, the test commands, the quality gates, and the release process. ARCHITECTURE.md has the module map, the component boundaries, and the design constraints.

API Token Generation

To generate an API token in Zammad:

1. Log into your Zammad instance

2. Click on your avatar → Profile

3. Navigate to "Token Access"

4. Click "Create"

5. Name your token (e.g., "MCP Server")

6. Select appropriate permissions

7. Copy the generated token

Troubleshooting

Connection Issues

• Verify your Zammad URL includes the protocol (https://)

• Check that your API token has the necessary permissions

• Ensure your Zammad instance is accessible from your network

• For self-signed/internal certs only: set ZAMMAD_INSECURE=true to bypass TLS verification

Authentication Errors

• Use API tokens over username/password

• Ensure tokens have permissions for the operations

• Check token expiration in Zammad settings

Rate Limiting

The client retries safe reads, can throttle requests, and opens a circuit breaker after repeated failures. When retries are exhausted or the circuit is open, tools return an Error: message that names the cause. A 429 outcome points at rate limiting and ZAMMAD_RATE_LIMIT_ENABLED. Reduce request frequency, paginate, or enable throttling if you keep hitting Zammad's limits. See Rate limiting, retries, and circuit breaker for the variables and the retry rules.

Security

The server implements multiple layers of protection following industry best practices.

Reporting Security Issues

⚠️ IMPORTANT: Do not create public GitHub issues for security vulnerabilities.

Report via GitHub Security Advisories (preferred) or see SECURITY.md.

Security Features

• ✅ Request Validation: Strict request models reject unknown fields and validate constrained inputs (models.py)

• ⚠️ URL Validation: Rejects malformed and non-HTTP(S) URLs, but does not block private-network targets (client.py)

• ✅ HTML Sanitization: Sanitizes selected HTML-bearing fields (models.py)

• ✅ Upstream Authentication: Supports API tokens, OAuth2, and username/password for Zammad (client.py)

• ✅ Audit Logging: Opt-in JSON Lines records for tool calls, connection outcomes, and URL checks with secret redaction (audit.py)

• ✅ Dependency Scanning: CI runs pip-audit; Dependabot security alerts are enabled separately in GitHub

• ✅ Security Testing: CI runs Bandit and pip-audit (security-scan.yml)

See SECURITY.md for complete documentation.

Contributing

See CONTRIBUTING.md for development setup, code standards, testing, and pull request guidelines.

License

AGPL-3.0-or-later — matches the Zammad project license.

Documentation

• Documentation index — Index of all documentation

• HTTP Transport Deployment Guide — Reverse proxy, systemd, Compose, cloud deployment, and webhook events

• Configuration reference — Every environment variable with its default and allowed values

• ARCHITECTURE.md — Technical design

• SECURITY.md — Security policy

• CONTRIBUTING.md — Development guidelines

• CHANGELOG.md — Version history

Support

• GitHub Issues

• Zammad Documentation

• MCP Documentation

Trademark Notice

"Zammad" is a trademark of Zammad GmbH. This independent integration is not affiliated with or endorsed by Zammad GmbH or the Zammad Foundation. The name "Zammad" indicates compatibility with the Zammad ticket system.