Zammad MCP Server — Quick Start

Install the Zammad MCP Server and verify connectivity with health_check in under 15 minutes.

Quick Start

Get the Zammad MCP Server talking to your instance in a few steps.

Prerequisites

  • Python 3.11+ (or use uvx without a global install)
  • A running Zammad instance (6.0+; current line 7.2.2, tested on 7.1 / 7.0 — self-hosted, cloud, or local Docker stack)
  • A Zammad HTTP API token (see below)

Create a Zammad API token

The MCP server authenticates with a personal access token from your Zammad profile. Official reference: Token access (Zammad user docs).

Step 1 — Open your profile

Click your user icon in the bottom-left corner of Zammad, then choose Profile.

Zammad user menu — open Profile from the avatar menu in the bottom-left corner.

Step 2 — Open Token Access

In the profile sidebar, select Token Access. Under Add a Personal Access Token, click Create.

Zammad Profile — Token Access page with the Create button for a new personal access token.

Step 3 — Name the token and set permissions

In the dialog Add a Personal Access Token:

  1. Enter a name you will recognize later (for example MCP_TOKEN or Cursor Zammad).
  2. Optionally set an expiration date.
  3. Enable the permissions your MCP workflows need. For typical ticket search, updates, and user lookup, include at least:
    • ticket.agent
    • user_preferences

If you use admin-only MCP tools (for example some group or system operations), you may need additional scopes — start with the minimum set and add permissions only if a tool returns access denied.

Add a Personal Access Token — enter a name, optional expiry, and select permission checkboxes.

Step 4 — Copy the token once

Zammad shows the token only once. Copy it immediately (use the copy button), store it in a password manager or your MCP env block, then confirm with OK, I’ve copied my token.

You will paste this value into ZAMMAD_HTTP_TOKEN in the next section. If you lose it, delete the token and create a new one.

Your New Personal Access Token — copy the token string before closing the dialog; it cannot be shown again.

1. Install

Recommended (one-shot run):

Bash
uvx zammad-mcp-server

Or install globally:

Bash
pip install zammad-mcp-server
# or
uv tool install zammad-mcp-server

2. Configure environment

Create a .env file in your working directory (or set variables in your MCP client config):

Env
ZAMMAD_URL=https://your-zammad-instance.example.com
ZAMMAD_HTTP_TOKEN=your_api_token_here
# Recommended: deny destructive tools by default
MCP_DENIED_TOOLS=delete_ticket,delete_user,delete_organization

See Configuration for all options.

3. Run the server (stdio)

For local MCP clients (Claude Desktop, Cursor):

Bash
zammad-mcp-server

The server uses stdio transport by default — the MCP client spawns this process and communicates over stdin/stdout.

4. Verify in your MCP client

After adding the server to Claude or Cursor, ask:

Run health_check on Zammad.

A successful response includes Zammad version information and confirms API connectivity.

Other useful first prompts:

  • “List open tickets assigned to me.”
  • “Search tickets with state.name:open AND group.name:Support.”
  • “Summarize ticket 12345 with summarize_ticket.”
  • “Call get_allowed_tools and show which tools are enabled.”

5. Optional — HTTP for remote clients

Version 0.2.0 defaults Docker to Streamable HTTP. For manual remote setups:

Bash
zammad-mcp-server --transport http --host 0.0.0.0 --port 8000

MCP path: /mcp/. There is no /health route — verify port 8000 is listening.

Legacy SSE (older MCP clients):

Bash
zammad-mcp-server --transport sse --host 0.0.0.0 --port 8000

Use only on trusted networks or behind authentication. See Deployment and Agent Workflows.

Try it with LibreChat

The package ships a Compose stack: LibreChat, MongoDB, and this MCP server. You need Docker, a Zammad URL, an API token, and an OpenRouter key.

Bash
git clone https://github.com/openticketai/zammad-mcp-server.git
cd zammad-mcp-server/examples/librechat
cp env.example .env

Set ZAMMAD_URL, ZAMMAD_HTTP_TOKEN, and OPENROUTER_API_KEY in .env. If Zammad is the dev stack on this machine (docker/ in the repo, port 8080), use http://host.docker.internal:8080.

Bash
docker compose up

Open http://localhost:3080, create an account, pick OpenRouter, and ask: Run health_check on Zammad.

Already installed from PyPI:

Bash
uvx zammad-mcp-server init librechat
cd librechat
cp env.example .env
docker compose up

Try it with Open WebUI

Same three values. Open WebUI v0.6.31 or newer connects over Streamable HTTP.

Bash
cd zammad-mcp-server/examples/open-webui
cp env.example .env

Set the same three variables, then:

Bash
docker compose up

Open http://localhost:3000. The first account is the admin. In a chat, enable the Zammad tool and ask for health_check.

Bash
uvx zammad-mcp-server init open-webui
cd open-webui
cp env.example .env
docker compose up

If the tool does not appear: Settings → Integrations → External Tool Servers → Add. Type MCP (Streamable HTTP), URL http://zammad-mcp:8000/mcp/, auth None.

Troubleshooting

SymptomCheck
Connection refusedZAMMAD_URL must include scheme (https://) and reach the instance from the host running MCP
401 / 403Token scope and user role; regenerate token in Zammad
Tool not foundMCP_DENIED_TOOLS or MCP_ALLOWED_CATEGORIES may block the tool — run get_allowed_tools
SSL errorsCorporate proxy or custom CA — set verify per deployment docs on GitHub

What’s next?