gruppohappy/zammad-mcp

ZammadMCP - Model Context Protocol Server for Zammad

A production-ready MCP (Model Context Protocol) server that provides seamless integration between Claude Desktop and Zammad helpdesk platform. Built with FastMCP and designed for enterprise helpdesk workflows.

🚀 Features

Core Capabilities

• Search Operations: Advanced ticket, user, and organization search with filtering
• Ticket Management: Full CRUD operations for tickets and articles
• Reporting & Analytics: Performance metrics, statistics, and trend analysis
• Custom Fields: Native support for Zammad custom fields (areatecnica, areaapplicativa, data_fine)
• Security: HTML sanitization, rate limiting, secure authentication
• Resilience: Circuit breaker pattern, retry logic, connection pooling

Integration Benefits

• Claude Desktop Ready: Direct integration with Claude for AI-powered helpdesk assistance
• Real-time Data: Live access to Zammad data without manual exports
• Workflow Automation: Leverage Claude's AI capabilities for ticket analysis and responses
• Custom Field Support: Full access to your organization's custom ticket fields

📋 Requirements

• Python 3.11+
• Zammad 6.5.0+ instance
• Personal Access Token with appropriate permissions
• Claude Desktop (for MCP integration)

🔧 Installation

1. Clone and Setup

git clone https://github.com/gruppohappy/zammad-mcp.git
cd zammad-mcp

2. Environment Configuration

# Copy example environment file
cp .env.example .env

# Edit configuration
nano .env

Required environment variables:

ZAMMAD_URL=https://helpdeskgh.prima-dom.locale
ZAMMAD_TOKEN=your_personal_access_token
ZAMMAD_USER=your_username

3. Install Dependencies

Using pip:

pip install -r requirements.txt

Using uv (recommended):

uv sync --dev --all-extras

🚦 Running the Server

Development Mode

# Using MCP CLI
mcp dev src/server.py

# Direct execution
python -m src.server

Production with Docker

# Build and run with Docker Compose
cd docker
docker-compose up -d

# Check logs
docker-compose logs -f zammad-mcp

🔌 Claude Desktop Integration

1. Install for Claude Desktop

# Install the MCP server
mcp install src/server.py --name "ZammadMCP"

# With environment variables
mcp install src/server.py -f .env

2. Manual Configuration

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "zammad": {
      "command": "python",
      "args": ["/path/to/ZammadMCP/src/server.py"],
      "env": {
        "ZAMMAD_URL": "https://helpdeskgh.prima-dom.locale",
        "ZAMMAD_TOKEN": "your_token",
        "ZAMMAD_USER": "your_username"
      }
    }
  }
}

🛠 Available Tools

Search Operations

search_tickets

Advanced ticket search with filtering capabilities.

Parameters:

• query: Text search in title/content
• state_ids: Filter by state (1=new, 2=open, 3=pending, 4=closed)
• priority_ids: Filter by priority (1=low, 2=normal, 3=high)
• group_ids: Filter by group IDs
• owner_ids: Filter by assigned agent IDs
• created_after/before: Date range filters
• areatecnica: Technical area filter
• areaapplicativa: Application area filter

Example Usage:

Search for open tickets in the Infrastructure area assigned to agent 123 created in the last week

search_users

Find users and customers by various criteria.

Parameters:

• query: Text search in name/email
• email: Exact email search
• organization_id: Filter by organization
• active: Filter by active status

search_organizations

Locate organizations by name or domain.

Ticket Management

get_ticket

Retrieve complete ticket details including custom fields and conversation history.

Example:

Get details for ticket 11658 including all articles

create_ticket

Create new tickets with full customization.

Required Parameters:

• title: Ticket subject
• group_id: Target group

Optional Parameters:

• customer_email: Customer email (creates if not exists)
• priority_id, state_id: Priority and state
• areatecnica, areaapplicativa: Custom technical areas
• data_fine: Deadline date
• article_body: Initial message

update_ticket

Modify existing tickets including custom fields.

add_article

Add replies, notes, or updates to tickets.

Reporting & Analytics

ticket_statistics

Generate comprehensive ticket statistics and breakdowns.

Features:

• Volume by state, priority, group
• Response and resolution time analytics
• Custom field distributions
• Date range filtering

agent_performance

Analyze agent productivity and performance metrics.

Metrics:

• Tickets assigned/resolved
• Average response/resolution times
• Recent activity (week/month)
• Resolution rates

time_analytics

Time-based trends and pattern analysis.

Options:

• Daily/weekly/monthly periods
• Configurable lookback periods
• Volume trends
• Performance trends

🏗 Architecture

System Design

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude        │    │   ZammadMCP     │    │   Zammad        │
│   Desktop       │◄──►│   Server        │◄──►│   Instance      │
│                 │    │                 │    │                 │
│   MCP Client    │    │   FastMCP       │    │   REST API      │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Core Components

• FastMCP Server: Modern MCP protocol implementation
• Zammad Client: Async API wrapper with retry logic
• Tool Modules: Organized by functionality (search, tickets, reports)
• Configuration: Environment-based with validation
• Error Handling: Comprehensive exception management

Custom Fields Support

Your Zammad custom fields are automatically supported:

• data_fine: Deadline management
• approvatori: Area owner assignment
• areatecnica: Technical area classification
• areaapplicativa: Sub-category specification

🔒 Security

Authentication

• PAT Authentication: Secure Personal Access Token usage
• User Context: Maintains Zammad user permissions
• No Credential Storage: Tokens passed via environment

Rate Limiting

• API Throttling: Configurable requests per minute
• Retry Logic: Exponential backoff on failures
• Connection Pooling: Efficient resource usage

Data Privacy

• No Data Persistence: All data retrieved in real-time
• Minimal Logging: Sensitive data automatically masked
• Secure Transport: HTTPS connections only

📊 Configuration Options

Environment Variables

Performance Tuning

# High-volume environments
RATE_LIMIT_PER_MINUTE=120
REQUEST_TIMEOUT=60
MAX_RETRIES=5

# Development/testing
DEBUG=true
LOG_LEVEL=DEBUG

🐳 Docker Deployment

Quick Start

# Clone repository
git clone <repository-url>
cd ZammadMCP

# Configure environment
cp .env.example .env
# Edit .env with your Zammad details

# Deploy with Docker Compose
cd docker
docker-compose up -d

Production Configuration

# docker-compose.override.yml
version: '3.8'
services:
  zammad-mcp:
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: '1.0'
    restart: always
    logging:
      driver: syslog
      options:
        syslog-address: "tcp://logserver:514"

🧪 Testing

Run Tests

# Install test dependencies
pip install -r requirements.txt

# Run test suite with coverage
python run_tests.py

# Or using pytest directly
pytest tests/ --cov=src --cov-report=html

Test Coverage

Current coverage: 65% (Target: 80%)

The comprehensive test suite includes:

• 74 tests covering all major components
• Unit tests for search, ticket, and report tools
• Integration tests with real Zammad API
• Circuit breaker and resilience patterns
• Security and sanitization tests
• Performance and load testing capabilities

See for detailed testing instructions.

🚨 Troubleshooting

Common Issues

Authentication Errors

Failed to authenticate with Zammad: Invalid authentication token

Solution: Verify your ZAMMAD_TOKEN and ZAMMAD_USER in the environment configuration.

Connection Timeouts

Connection failed after 3 attempts

Solution: Check ZAMMAD_URL accessibility and increase REQUEST_TIMEOUT.

Rate Limiting

Rate limit exceeded

Solution: Reduce RATE_LIMIT_PER_MINUTE or implement request batching.

Debug Mode

Enable detailed logging:

DEBUG=true
LOG_LEVEL=DEBUG

Health Checks

# Check server health
curl http://localhost:3000/health

# Docker health check
docker-compose ps

🤝 Contributing

We welcome contributions! Please see our for details.

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Or using uv
uv sync --dev --all-extras

# Setup pre-commit hooks
pre-commit install

# Run quality checks
black src/ tests/
isort src/ tests/
pytest tests/

CI/CD Pipeline

All pull requests are automatically tested with:

• Unit tests and coverage checks
• Code formatting (Black, isort)
• Security scanning (Bandit, Safety)
• Docker build verification
• Dependency vulnerability scanning

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Zammad Team: For the excellent helpdesk platform
• Anthropic: For the MCP protocol and Claude integration
• FastMCP: For the modern Python MCP framework
• Community: For Python async/await ecosystem

📚 Documentation

• - Comprehensive testing instructions
• - Tools for understanding Zammad API
• - Project status and future plans
• - Detailed version history

🏗️ Project Status

Version: 1.1.0 (Stable)

Build Status

Workflow	Status
CI/CD
Security
Coverage

Completed Features ✅

• All core functionality implemented
• Full search, ticket, and reporting operations
• Custom field support
• Security implementation (HTML sanitization)
• CI/CD pipeline with GitHub Actions
• Comprehensive test suite (189 tests, 78% coverage)
• Docker deployment support
• MyPy type checking (all errors fixed)

Recent Updates 🎉

• Fixed all 17 MyPy type errors
• Test coverage increased to 78%
• All reporting tools fully implemented
• Production-ready with resilience patterns

Need Help? Open an issue or check the for detailed guides.

Enterprise Support? Contact us for custom implementations and support packages.