Zammad客服助手MCP

Install development dependencies

uv pip install -e ".[dev]"

Installation

Install uv if you haven't already

Option 2: Docker Run

For production or containerized deployments:

```bash

Using Docker secrets for better security

docker run --rm -i \ -e ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \ -e ZAMMAD_HTTP_TOKEN_FILE=/run/secrets/token \ -v ./secrets/zammad_http_token.txt:/run/secrets/token:ro \ ghcr.io/basher83/zammad-mcp:latest

Run the setup script

HTTP Transport (Remote/Cloud Deployment)

The server supports Streamable HTTP transport for remote deployments.

Environment Configuration

Set these environment variables to enable HTTP transport:

export MCP_TRANSPORT=http    # Enable HTTP transport
export MCP_HOST=127.0.0.1    # Host to bind (default: 127.0.0.1)
export MCP_PORT=8000         # Port to listen on

Running with HTTP Transport

Direct Python:

MCP_TRANSPORT=http \
MCP_HOST=127.0.0.1 \
MCP_PORT=8000 \
ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \
ZAMMAD_HTTP_TOKEN=your-api-token \
uvx --from git+https://github.com/basher83/zammad-mcp.git mcp-zammad

Docker:

docker run -d \
  --name zammad-mcp-http \
  -p 8000:8000 \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \
  -e ZAMMAD_HTTP_TOKEN=your-api-token \
  ghcr.io/basher83/zammad-mcp:latest

Access the MCP endpoint at http://localhost:8000/mcp/.

Production Deployment with Reverse Proxy

⚠️ SECURITY WARNING: Bind to 0.0.0.0 only behind a reverse proxy with TLS.

Use a reverse proxy (nginx/Caddy) for HTTPS and security:

Example with Caddy:

```bash

Setup

Using Setup Scripts (Recommended)

```bash

Run the setup script

Install in development mode

uv pip install -e ".[dev]" ```

Basic usage with environment variables

docker run --rm -i \ -e ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \ -e ZAMMAD_HTTP_TOKEN=your-api-token \ ghcr.io/basher83/zammad-mcp:latest

Usage

Standalone Usage

```bash

Examples

Option 1: Run Directly with uvx (Recommended)

Run without installation:

```bash

Or with environment variables

ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \ ZAMMAD_HTTP_TOKEN=your-api-token \ uvx --from git+https://github.com/basher83/zammad-mcp.git mcp-zammad ```

With .env file

docker run --rm -i \ --env-file .env \ ghcr.io/basher83/zammad-mcp:latest

#### Docker Image Versioning

The project publishes Docker images with semantic versioning:

- `latest` - Most recent stable release
- `1.2.3` - Specific version (recommended for production)
- `1.2` - Latest patch of 1.2 minor release
- `1` - Latest minor/patch of 1.x major release
- `main` - Latest main branch (may be unstable)

Option 3: For Developers

To contribute or modify the code:

```bash

Configuration

The server requires Zammad API credentials. Use a .env file:

1. Copy the example configuration:

   cp .env.example .env
   

1. Edit .env with your Zammad credentials:

   # Required: Zammad instance URL (include /api/v1)
   ZAMMAD_URL=https://your-instance.zammad.com/api/v1

   # Authentication (choose one method):
   # Option 1: API Token (recommended)
   ZAMMAD_HTTP_TOKEN=your-api-token

   # Option 2: OAuth2 Token
   # ZAMMAD_OAUTH2_TOKEN=your-oauth2-token

   # Option 3: Username/Password
   # ZAMMAD_USERNAME=your-username
   # ZAMMAD_PASSWORD=your-password

   # Optional: Disable TLS certificate verification (NOT recommended for production)
   # Truthy values only: 1, true, yes, on. Unset (default) keeps TLS verification enabled.
   # ZAMMAD_INSECURE=true

   # Optional: Logging level (default: INFO)
   # Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL
   # LOG_LEVEL=INFO

   # Optional: Transport Configuration
   # MCP_TRANSPORT=stdio  # Transport type: stdio (default) or http
   # MCP_HOST=127.0.0.1   # Host address for HTTP transport
   # MCP_PORT=8000        # Port number for HTTP transport
   

1. The server will automatically load the .env file on startup.

Transport Configuration (Optional)

Important: Keep your .env file out of version control (already in .gitignore).

Or with environment variables

ZAMMAD_URL=https://instance.zammad.com/api/v1 ZAMMAD_HTTP_TOKEN=token python -m mcp_zammad ```

Create a virtual environment with uv

uv venv

Activate the virtual environment

.venv\Scripts\activate

Start the MCP server (binds to all interfaces for reverse proxy)

MCP_TRANSPORT=http \ MCP_HOST=0.0.0.0 \ MCP_PORT=8000 \ ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \ ZAMMAD_HTTP_TOKEN=your-api-token \ uvx --from git+https://github.com/basher83/zammad-mcp.git mcp-zammad

**Caddyfile configuration:**

**Production checklist:**

1. Use `MCP_HOST=0.0.0.0` only behind a reverse proxy
2. Enable HTTPS/TLS via reverse proxy
3. Implement authentication at the proxy or application layer
4. Restrict access with firewall rules

#### Client Configuration for HTTP

Configure your MCP client to use HTTP transport:

Security Considerations

1. Local Development: Use MCP_HOST=127.0.0.1 (localhost only)
2. Production: Implement authentication (see Security)
3. HTTPS: Use reverse proxy for TLS
4. Firewall: Restrict access to trusted networks
5. DNS Rebinding: Built-in origin validation protects against these attacks

API Token Generation

To generate an API token in Zammad:

1. Log into your Zammad instance
2. Click on your avatar → Profile
3. Navigate to "Token Access"
4. Click "Create"
5. Name your token (e.g., "MCP Server")
6. Select appropriate permissions
7. Copy the generated token

Troubleshooting