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

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…[redacted] \
  -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)

| Variable | Default | Description | |----------|---------|-------------| | MCP_TRANSPORT | stdio | Transport type: stdio or http | | MCP_HOST | 127.0.0.1 | Host address for HTTP transport | | MCP_PORT | - | Port number for HTTP transport (required if MCP_TRANSPORT=http) |

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