Zammad MCP Server — Claude & Cursor Setup
Configure Claude Desktop and Cursor to use the Zammad MCP Server via uvx or a local install — with screenshots for the Zammad token flow.
Claude & Cursor Setup
Both Claude Desktop and Cursor support MCP servers that run as local subprocesses (stdio transport). You need two things before editing MCP config:
- A Zammad personal access token — walkthrough with screenshots in Quick Start → Create a Zammad API token
- Your Zammad base URL (
https://helpdesk.example.com)
Cursor — step by step
- Open Cursor Settings (gear icon) → MCP (or Features → MCP depending on your Cursor version).
- Click Add MCP server or edit the JSON config file Cursor shows.
- Paste the configuration below. Replace
ZAMMAD_URLandZAMMAD_HTTP_TOKENwith your values. - Save and reload MCP servers (or restart Cursor).
- Open a chat and ask: “Run
health_checkon Zammad.” - Optional: “Call
get_allowed_toolsand list enabled tools.”
Example configuration:
{ "mcpServers": { "zammad": { "command": "uvx", "args": ["zammad-mcp-server"], "env": { "ZAMMAD_URL": "https://your-zammad-instance.example.com", "ZAMMAD_HTTP_TOKEN": "your_token", "MCP_DENIED_TOOLS": "delete_ticket,delete_user,delete_organization" } } }}Pin the package version in production configs:
"args": ["zammad-mcp-server==0.2.0"]Using a local venv instead of uvx:
{ "mcpServers": { "zammad": { "command": "C:\\path\\to\\.venv\\Scripts\\zammad-mcp-server.exe", "env": { "ZAMMAD_URL": "https://your-zammad-instance.example.com", "ZAMMAD_HTTP_TOKEN": "your_token" } } }}On macOS/Linux, point command to the zammad-mcp-server binary inside your virtualenv.
Zammad token screenshots (Cursor setup uses the same token)
| Step | What you do in Zammad |
|---|---|
| 1 | Profile → Token Access → Create — screenshot |
| 2 | Name the token, enable ticket.agent (+ user_preferences) — screenshot |
| 3 | Copy the secret once — screenshot |
Paste the copied value into the ZAMMAD_HTTP_TOKEN field in Cursor’s MCP config.
Claude Desktop
Config file locations:
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
Use the same JSON structure as the Cursor example above. Restart Claude Desktop after saving.
Zammad 7.2 notes
The MCP server uses the Zammad REST API only — no Zammad-side plugin is required.
| Zammad version | MCP impact |
|---|---|
| 7.2.2 (latest stable) | Current release — upgrade Zammad for the 7.2 security patches |
| 7.2.x / 7.1.x / 7.0.x | Compatible; 7.0 and 7.1 tested. PostgreSQL on Zammad 7 |
| 6.5.x – 6.0 | Compatible via the same REST API |
After connecting, run get_server_info to confirm the Zammad version the token sees.
Local Zammad (Docker dev stack)
If you use the docker-compose dev environment:
"env": { "ZAMMAD_URL": "http://localhost:8080", "ZAMMAD_HTTP_TOKEN": "your_dev_token"}Default admin credentials in the dev stack are documented in the GitHub README — change them before exposing the instance.
Example workflows
Once connected, you can ask your assistant to:
- Search and summarize long ticket threads
- Draft customer-facing replies (you review before
create_article) - List organizations or users matching criteria
- Report ticket stats for a date range
Always review AI-generated ticket updates before applying them in production.
Troubleshooting
| Symptom | Fix |
|---|---|
| MCP server does not appear in Cursor | Restart Cursor; validate JSON (no trailing commas) |
health_check fails with 401/403 | Regenerate token; confirm ticket.agent scope |
| Connection error | ZAMMAD_URL must include https:// and be reachable from your PC |
| Tool missing | Check MCP_DENIED_TOOLS — run get_allowed_tools |
| Wrong Zammad version reported | Upgrade Zammad to 7.2.2 if you are on an older 7.x patch |
Security reminder
- Never commit tokens into git-tracked config files.
- Prefer
MCP_DENIED_TOOLSfor delete operations in agent-facing setups. - See Configuration for role-based policy recipes and Security for production checklists.
