Zammad MCP Server

An MCP server exposing a Zammad helpdesk to a model. Built on zammad-python-client; it owns tool design, safety and response shaping and no HTTP logic at all.

Fifteen tools shaped like support jobs, not CRUD:

Deliberately absent: delete anything, merge tickets, publish an answer publicly, mail a customer without send=true. Every write is something an agent does all day and can undo in the UI.

Install

On PyPI as zammad-mcp; the server itself needs no install step:

claude mcp add --scope user zammad -e ZAMMAD_URL=https://zammad.example.com -e ZAMMAD_TOKEN=... -- uvx zammad-mcp

Any MCP client: command uvx, args ["zammad-mcp"], env ZAMMAD_URL and ZAMMAD_TOKEN. Teams on our marketplace install the zammad plugin instead, which asks for the token on install.

From a checkout: uv venv && uv pip install -e ".[dev]", then .venv/bin/zammad-mcp with ZAMMAD_URL / ZAMMAD_TOKEN in .env.

Token: create a dedicated agent user in Zammad (e.g. mcp) with only the groups the model should see, ticket.agent, knowledge_base.reader and, if it may write answers, knowledge_base.editor. Generate the token under that user's profile. Never use an admin token.

Behaviour

• Lists are capped (ZAMMAD_MCP_DEFAULT_LIMIT, ZAMMAD_MCP_MAX_LIMIT) and say so in notes.
• Article and answer bodies are HTML-to-text and cut at ZAMMAD_MCP_BODY_CHARS, disclosed in notes.
• Errors come back as {"error": "<sentence>"}, never as exceptions.
• One client per worker thread; the SDK runs tool handlers concurrently.

Development

pytest -q   # fake client + one real stdio handshake, no network
mypy
scripts/verify-live.py --ticket <id>   # read-only tools against a real instance (.env)

Releases: bump version in pyproject.toml and __version__ in src/zammad_mcp/__init__.py together, tag vX.Y.Z; CI publishes to PyPI.