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:

  1. A Zammad personal access token — walkthrough with screenshots in Quick Start → Create a Zammad API token
  2. Your Zammad base URL (https://helpdesk.example.com)

Cursor — step by step

  1. Open Cursor Settings (gear icon) → MCP (or Features → MCP depending on your Cursor version).
  2. Click Add MCP server or edit the JSON config file Cursor shows.
  3. Paste the configuration below. Replace ZAMMAD_URL and ZAMMAD_HTTP_TOKEN with your values.
  4. Save and reload MCP servers (or restart Cursor).
  5. Open a chat and ask: “Run health_check on Zammad.”
  6. Optional: “Call get_allowed_tools and list enabled tools.”

Example configuration:

JSON
{
"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:

JSON
"args": ["zammad-mcp-server==0.2.0"]

Using a local venv instead of uvx:

JSON
{
"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)

StepWhat you do in Zammad
1Profile → Token Access → Create — screenshot
2Name the token, enable ticket.agent (+ user_preferences) — screenshot
3Copy the secret once — screenshot

Paste the copied value into the ZAMMAD_HTTP_TOKEN field in Cursor’s MCP config.

Claude Desktop

Config file locations:

OSPath
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 versionMCP impact
7.2.2 (latest stable)Current release — upgrade Zammad for the 7.2 security patches
7.2.x / 7.1.x / 7.0.xCompatible; 7.0 and 7.1 tested. PostgreSQL on Zammad 7
6.5.x – 6.0Compatible 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:

JSON
"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

SymptomFix
MCP server does not appear in CursorRestart Cursor; validate JSON (no trailing commas)
health_check fails with 401/403Regenerate token; confirm ticket.agent scope
Connection errorZAMMAD_URL must include https:// and be reachable from your PC
Tool missingCheck MCP_DENIED_TOOLS — run get_allowed_tools
Wrong Zammad version reportedUpgrade 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_TOOLS for delete operations in agent-facing setups.
  • See Configuration for role-based policy recipes and Security for production checklists.