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

Step 2 — Open Token Access
In the profile sidebar, select Token Access. Under Add a Personal Access Token, click Create.

Step 3 — Name the token and set permissions
In the dialog Add a Personal Access Token:
- Enter a name you will recognize later (for example
MCP_TOKENorCursor Zammad). - Optionally set an expiration date.
- 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.

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.

1. Install
Recommended (one-shot run):
uvx zammad-mcp-serverOr install globally:
pip install zammad-mcp-server# oruv tool install zammad-mcp-server2. Configure environment
Create a .env file in your working directory (or set variables in your MCP client config):
ZAMMAD_URL=https://your-zammad-instance.example.comZAMMAD_HTTP_TOKEN=your_api_token_here
# Recommended: deny destructive tools by defaultMCP_DENIED_TOOLS=delete_ticket,delete_user,delete_organizationSee Configuration for all options.
3. Run the server (stdio)
For local MCP clients (Claude Desktop, Cursor):
zammad-mcp-serverThe 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_checkon 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_toolsand show which tools are enabled.”
5. Optional — HTTP for remote clients
Version 0.2.0 defaults Docker to Streamable HTTP. For manual remote setups:
zammad-mcp-server --transport http --host 0.0.0.0 --port 8000MCP path: /mcp/. There is no /health route — verify port 8000 is listening.
Legacy SSE (older MCP clients):
zammad-mcp-server --transport sse --host 0.0.0.0 --port 8000Use 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.
git clone https://github.com/openticketai/zammad-mcp-server.gitcd zammad-mcp-server/examples/librechatcp env.example .envSet 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.
docker compose upOpen http://localhost:3080, create an account, pick OpenRouter, and ask: Run health_check on Zammad.
Already installed from PyPI:
uvx zammad-mcp-server init librechatcd librechatcp env.example .envdocker compose upTry it with Open WebUI
Same three values. Open WebUI v0.6.31 or newer connects over Streamable HTTP.
cd zammad-mcp-server/examples/open-webuicp env.example .envSet the same three variables, then:
docker compose upOpen http://localhost:3000. The first account is the admin. In a chat, enable the Zammad tool and ask for health_check.
uvx zammad-mcp-server init open-webuicd open-webuicp env.example .envdocker compose upIf the tool does not appear: Settings → Integrations → External Tool Servers → Add. Type MCP (Streamable HTTP), URL http://zammad-mcp:8000/mcp/, auth None.
Troubleshooting
| Symptom | Check |
|---|---|
| Connection refused | ZAMMAD_URL must include scheme (https://) and reach the instance from the host running MCP |
| 401 / 403 | Token scope and user role; regenerate token in Zammad |
| Tool not found | MCP_DENIED_TOOLS or MCP_ALLOWED_CATEGORIES may block the tool — run get_allowed_tools |
| SSL errors | Corporate proxy or custom CA — set verify per deployment docs on GitHub |
What’s next?
- Claude & Cursor Setup
- Agent Workflows — summarize_ticket, tags, attachments
- Security before team-wide rollout
- Full Tools Reference
