Zammad MCP Server — Configuration

Environment variables, authentication, and access control for the Zammad MCP Server.

Configuration

The server is configured through environment variables (.env file or MCP client env block).

Required

Variable	Description
`ZAMMAD_URL`	Base URL of your Zammad instance, e.g. `https://helpdesk.example.com`
`ZAMMAD_HTTP_TOKEN`	Personal access token from Zammad Profile → Token Access — see the Quick Start token walkthrough with screenshots

Token setup (screenshots)

The MCP server never stores passwords in config files — only the HTTP token. Create it once in Zammad:

Profile → Token Access → Create — enable ticket.agent (and user_preferences for profile reads).
Copy the secret immediately; Zammad shows it only once.
Paste into ZAMMAD_HTTP_TOKEN in your Claude or Cursor MCP config.

Visual walkthrough: Quick Start steps 1–4.

Authentication alternatives

Variable	When to use
`ZAMMAD_HTTP_TOKEN`	Default — recommended for MCP and automation
OAuth2 client settings	As documented in the GitHub DEPLOYMENT guide
Basic auth	Legacy environments only — prefer tokens

Refer to Zammad API authentication for authoritative token behavior.

Access control

The MCP server enforces permissions before executing tools.

Permission levels

Level	Behavior
`DENIED`	Tool not exposed to the client
`READ_ONLY`	View data only
`WRITE`	Create and update
`ADMIN`	Includes delete operations

Environment variables

# Allow all tool categories (default)
MCP_ALLOWED_CATEGORIES=all

# Restrict to specific categories
MCP_ALLOWED_CATEGORIES=tickets,groups,system

# Deny dangerous tools (recommended for agents)
MCP_DENIED_TOOLS=delete_ticket,delete_user,delete_organization

# Optional: limit to Zammad groups (reads and writes)
MCP_ALLOWED_GROUPS=Support,Sales

# Optional: limit to organization IDs
MCP_ALLOWED_ORGANIZATIONS=1,2

# Read-only preset
MCP_DEFAULT_PERMISSION=read_only

# Rate limit (0 disables)
MCP_RATE_LIMIT_PER_MINUTE=60

# Optional audit log file (stderr JSON always on)
MCP_AUDIT_LOG_PATH=/var/log/zammad-mcp-audit.jsonl

Transport (remote MCP)

Used when the server is not spawned by Claude/Cursor (Docker, Zammad Commander, remote agents):

Variable / flag	Default	Description
`--transport`	`stdio`	`stdio`, `http`, or `sse`
`MCP_TRANSPORT`	—	Same as `--transport`
`MCP_SERVER_HOST`	`127.0.0.1`	Bind address (`0.0.0.0` in Docker)
`MCP_SERVER_PORT`	`8000`	HTTP/SSE port
`MCP_SERVER_PATH`	`/mcp/`	HTTP path (`/sse/` for SSE)

Docker image CMD: zammad-mcp-server --transport http --host 0.0.0.0 --port 8000.

Article formatting

Variable	Default	Description
`MCP_STRIP_HTML`	`1`	Add `body_plain` on articles in tool responses

Set MCP_STRIP_HTML=0 only if your agent needs raw HTML bodies.

Production policy recipes

Copy one of these blocks into your MCP client env section (see Claude & Cursor setup).

Read-only triage assistant (search + summarize, no writes):

MCP_ALLOWED_CATEGORIES=tickets,search,system
MCP_DENIED_TOOLS=create_ticket,update_ticket,delete_ticket,create_article,delete_user,delete_organization,create_user,update_user

Support lead (search, summarize, internal notes — no deletes):

MCP_ALLOWED_CATEGORIES=all
MCP_DENIED_TOOLS=delete_ticket,delete_user,delete_organization
MCP_ALLOWED_GROUPS=Support

Admin automation (full write — use only with human review):

MCP_ALLOWED_CATEGORIES=all
MCP_DENIED_TOOLS=

Start with the read-only recipe, then widen permissions only when a tool returns access denied.

Inspect effective policy

Ask your MCP client to call get_allowed_tools — it returns the tools available under the current policy.

Programmatic policies

For embedded or multi-tenant setups, see AccessController and AccessPolicy in the GitHub architecture doc.

Caching

Static Zammad metadata (states, priorities, groups) is cached to reduce API load. Cache behavior is automatic; no configuration required for typical deployments.

Logging

Structured logging via structlog is enabled by default. Set log level through standard environment conventions in your process manager or container orchestrator.