zammad-mcp

MCP server for Zammad that focuses on workflows the standard Zammad API tooling does not cover well — primarily shared drafts with strict reply-HTML validation, fresh signature rendering and German- localised quote blocks.

Built to coexist with generic Zammad MCP servers (e.g. basher83/zammad-mcp) — this one deliberately covers only a narrow set of opinionated workflows.

Tools

• zammad_create_shared_draft — Reply-All shared draft with strict reply-HTML validation and signature rendering.

• zammad_get_ticket_thread — Ticket meta + all articles (with bodies) in one round-trip.

• zammad_add_internal_note — Append an internal note (hard-coded type=note, internal=true).

zammad_create_shared_draft

Creates or overwrites the shared draft of a Zammad ticket as a Reply-All email.

What the server does automatically:

• Finds the last incoming customer article (sender=Customer, type=email; falls back to the most recent article if none).

• Computes to, cc, subject, in_reply_to and from from that article plus /users/me and the ticket's group email-address.

• Filters configured self-addresses out of CC (so you don't reply to yourself).

• Fetches the signature template fresh from Zammad and resolves all #{...} placeholders via lazy-loaded sub-objects (with caching). Defensively strips HTML tags that may have crept into placeholders via the Zammad WYSIWYG editor.

• Appends the original article as a German-localised <blockquote> with Europe/Berlin date (CET/CEST aware).

• Wraps the signature in <div data-signature="true" data-signature-id="X"> so Zammad does not stack a second signature on top when the draft is opened.

• PUTs the assembled payload to /tickets/<id>/shared_draft.

What you provide:

• ticket_id — Zammad ticket ID (numeric, from the URL /#ticket/zoom/<id>).

• reply_html — the actual reply body as HTML with a nested <div> structure (see validation below).

• signature_id (optional, default 1) — which signature to render.

• extra_cc (optional) — additional CC addresses to add on top of the automatic Reply-All set.

• quote_locale (optional, en or de) — language for the quote block's date format and "wrote:" lead-in. When omitted, the server default (ZAMMAD_QUOTE_LOCALE, falling back to en) is used.

Reply-HTML validation

The tool refuses the call if any of these issues are found in reply_html:

Universal checks (P_TAG, DOUBLE_BR, ASCII_QUOTE, WRONG_CLOSING_QUOTE, ASCII_APOSTROPHE) are always on. The two configurable checks are silent when their respective env-var is empty.

Example reply_html

<div>
  <div>Dear Mr Smith,</div>
  <div><br></div>
  <div>thank you for your message — we have resolved the issue.</div>
  <div><br></div>
  <div>Best regards</div>
</div>

Response

{
  "ok": true,
  "ticket_url": "https://zammad.example.com/#ticket/zoom/12345",
  "to": "customer@example.com",
  "cc": "colleague@example.com",
  "from": "Jane Doe <support@example.com>",
  "subject": "RE: Question about hosting",
  "in_reply_to": "<abc123@example.com>",
  "reference_article_id": 98765,
  "draft_id": null
}

(draft_id is null whenever Zammad does not return an id in the PUT response — the draft is still created, only the metadata is absent.)

On validation failure:

{
  "ok": false,
  "error": "INVALID_REPLY_HTML",
  "issues": [
    { "code": "P_TAG", "msg": "Top-level <p>-Tag bei Char 142 gefunden. ..." }
  ]
}

zammad_get_ticket_thread

Fetches a ticket and all of its articles in a single call. Useful for "give me context on ticket X before I write anything" — combines two Zammad endpoints (/tickets/<id>?expand=true and /ticket_articles/by_ticket/<id>) and returns a flat structure with ticket meta plus the article list.

Parameters:

• ticket_id — numeric ticket ID.

• include_internal (default true) — set to false to hide internal notes from the result.

• include_bodies (default true) — set to false to get a cheap meta- only overview of long threads.

• max_articles (optional) — caps to the most recent N articles.

Response: { ok, ticket_url, ticket: {...}, article_count_returned, article_count_total, truncated, articles: [...] }.

zammad_add_internal_note

Appends an internal note to a ticket. The tool hard-codes type: "note" and internal: true, so it is structurally impossible to accidentally send an email to the customer. For customer-facing content use zammad_create_shared_draft and let a human send the draft from the Zammad UI.

Parameters:

• ticket_id — numeric ticket ID.

• body — body content (HTML or plain text).

• content_type — text/html (default) or text/plain.

• subject (optional) — internal-list subject.

Response: { ok, ticket_url, article_id, type, internal }.

Related MCP server: einvoice-mcp

Setup

git clone <repo-url> zammad-mcp
cd zammad-mcp
npm install
npm run build
npm test

Node 18 or higher.

Configuration

See .env.example for a starter file.

Registration with Claude

Add this block to mcpServers in your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and / or your Claude Code config (~/.claude.json):

"zammad-mcp": {
  "command": "node",
  "args": ["/absolute/path/to/zammad-mcp/dist/index.js"],
  "env": {
    "ZAMMAD_URL": "https://mail.example.com/api/v1/",
    "ZAMMAD_HTTP_TOKEN": "...",
    "ZAMMAD_SELF_EMAILS": "support@example.com,me@example.com",
    "ZAMMAD_BANNED_NAMES": "Jane Doe,Jane",
    "ZAMMAD_REQUIRED_GREETING": "Best regards",
    "ZAMMAD_QUOTE_LOCALE": "en"
  }
}

Restart Claude Desktop completely (Cmd+Q + re-open) so the daemon reloads the MCP server list. In Claude Code a new chat is enough.

Tests

npm test

Unit tests use Node's built-in test runner via --experimental-strip-types. The signature resolver is tested with a mock Zammad client; everything else is pure logic and doesn't need network access.

License

MIT