basher83/Zammad-MCP

Zammad MCP Server

A Model Context Protocol (MCP) server for Zammad integration, enabling AI assistants to interact with tickets, users, organizations, and more through a standardized interface.

Disclaimer: This project is not affiliated with or endorsed by Zammad GmbH or the Zammad Foundation. This is an independent integration that uses the Zammad API.

Features

Tools

• Ticket Management

  • search_tickets - Search tickets with multiple filters
  • get_ticket - Get detailed ticket information with articles (supports pagination)
  • create_ticket - Create new tickets
  • update_ticket - Update ticket properties
  • add_article - Add comments/notes to tickets
  • add_ticket_tag / remove_ticket_tag - Manage ticket tags

• User & Organization Management

  • get_user / search_users - User information and search
  • get_organization / search_organizations - Organization data
  • get_current_user - Get authenticated user info

• System Information

  • list_groups - Get all available groups
  • list_ticket_states - Get all ticket states
  • list_ticket_priorities - Get all priority levels
  • get_ticket_stats - Get ticket statistics

Resources

Direct access to Zammad data:

• zammad://ticket/{id} - Individual ticket details
• zammad://user/{id} - User profile information
• zammad://organization/{id} - Organization details

Prompts

Pre-configured prompts for common tasks:

• analyze_ticket - Comprehensive ticket analysis
• draft_response - Generate ticket responses
• escalation_summary - Summarize escalated tickets

Installation

Option 1: Run Directly with uvx (Recommended)

The quickest way to use the MCP server without installation:

# Install uv if you haven't already
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Run directly from GitHub
uvx --from git+https://github.com/basher83/zammad-mcp.git mcp-zammad

# 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

Option 2: Docker Run

For production deployments or when you need more control:

# 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

# 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

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

Docker Image Versioning

Docker images are published 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)

# Recommended for production - pin to specific version
docker pull ghcr.io/basher83/zammad-mcp:1.0.0

View all versions on GitHub Container Registry.

Option 3: For Developers

If you're contributing to the project or need to modify the code:

# Clone the repository
git clone https://github.com/basher83/zammad-mcp.git
cd zammad-mcp

# Run the setup script
# On macOS/Linux:
./setup.sh

# On Windows (PowerShell):
.\setup.ps1

For manual setup, see the Development section below.

Configuration

The server requires Zammad API credentials. The recommended approach is to use a .env file:

1. Copy the example configuration:

   cp .env.example .env
   

2. 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
   

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

Important: Never commit your .env file to version control. It's already included in .gitignore.

Usage

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "zammad": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/basher83/zammad-mcp.git", "mcp-zammad"],
      "env": {
        "ZAMMAD_URL": "https://your-instance.zammad.com/api/v1",
        "ZAMMAD_HTTP_TOKEN": "your-api-token"
      }
    }
  }
}

Or using Docker:

{
  "mcpServers": {
    "zammad": {
      "command": "docker",
      "args": ["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"]
    }
  }
}

Note: MCP servers communicate via stdio (stdin/stdout), not HTTP. The -i flag is required for interactive mode. Port mapping (-p 8080:8080) is not needed for MCP operation.

Important: The container must run in interactive mode (-i) or the MCP server will not receive stdin. Ensure this flag is preserved in any wrapper scripts or shell aliases.

Or if you have it installed locally:

{
  "mcpServers": {
    "zammad": {
      "command": "python",
      "args": ["-m", "mcp_zammad"],
      "env": {
        "ZAMMAD_URL": "https://your-instance.zammad.com/api/v1",
        "ZAMMAD_HTTP_TOKEN": "your-api-token"
      }
    }
  }
}

Standalone Usage

# Run the server
python -m mcp_zammad

# Or with environment variables
ZAMMAD_URL=https://instance.zammad.com/api/v1 ZAMMAD_HTTP_TOKEN=token python -m mcp_zammad

Examples

Search for Open Tickets

Use search_tickets with state="open" to find all open tickets

Create a Support Ticket

Use create_ticket with:
- title: "Customer needs help with login"
- group: "Support"
- customer: "customer@example.com"
- article_body: "Customer reported unable to login..."

Update and Respond to a Ticket

1. Use get_ticket with ticket_id=123 to see the full conversation
2. Use add_article to add your response
3. Use update_ticket to change state to "pending reminder"

Analyze Escalated Tickets

Use the escalation_summary prompt to get a report of all tickets approaching escalation

Development

Setup

For development, you have two options:

Using Setup Scripts (Recommended)

# Clone the repository
git clone https://github.com/basher83/zammad-mcp.git
cd zammad-mcp

# Run the setup script
# On macOS/Linux:
./setup.sh

# On Windows (PowerShell):
.\setup.ps1

Manual Setup

# Clone the repository
git clone https://github.com/basher83/zammad-mcp.git
cd zammad-mcp

# Create a virtual environment with uv
uv venv

# Activate the virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
# .venv\Scripts\activate

# Install in development mode
uv pip install -e ".[dev]"

Project Structure

zammad-mcp/
├── mcp_zammad/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py      # MCP server implementation
│   ├── client.py      # Zammad API client wrapper
│   └── models.py      # Pydantic models
├── tests/
├── scripts/
│   └── uv/            # UV single-file scripts
├── pyproject.toml
├── README.md
├── Dockerfile
└── .env.example

Running Tests

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=mcp_zammad

Code Quality

# Format code
uv run ruff format mcp_zammad tests

# Lint
uv run ruff check mcp_zammad tests

# Type checking
uv run mypy mcp_zammad

# Run all quality checks
./scripts/quality-check.sh

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

Connection Issues

• Verify your Zammad URL includes the protocol (https://)
• Check that your API token has the necessary permissions
• Ensure your Zammad instance is accessible from your network

Authentication Errors

• API tokens are preferred over username/password
• Tokens must have appropriate permissions for the operations
• Check token expiration in Zammad settings

Rate Limiting

The server respects Zammad's rate limits. If you encounter rate limit errors:

• Reduce the frequency of requests
• Use pagination for large result sets
• Consider caching frequently accessed data

Contributing

See for detailed guidelines on:

• Development setup
• Code style and quality standards
• Testing requirements
• Pull request process
• GitHub workflows and CI/CD pipeline

License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) - see LICENSE file for details

This project uses the same license as the Zammad project to ensure compatibility and alignment with the upstream project.

Documentation

• - Technical architecture and design decisions
• - Development guidelines and contribution process
• - Version history and changes

Support

• GitHub Issues:
• Zammad Documentation:
• MCP Documentation:

Trademark Notice

"Zammad" is a trademark of Zammad GmbH. This project is an independent integration and is not affiliated with, endorsed by, or sponsored by Zammad GmbH or the Zammad Foundation. The use of the name "Zammad" is solely to indicate compatibility with the Zammad ticket system.