OTRS MCP Server

Ein Model Context Protocol-Server (MCP) für die OTRS-API-Integration (Open Ticket Request System).

Dies bietet Zugriff auf die OTRS-Ticketverwaltung über standardisierte MCP-Schnittstellen und ermöglicht es KI-Assistenten, Tickets zu erstellen, zu suchen und zu verwalten.

Funktionen

• Tickets erstellen, lesen, aktualisieren und suchen

• Zugriff auf Ticketverlauf und detaillierte Informationen

• Konfigurierbare Standardwerte für Tickets

• Unterstützung für Docker-Containerisierung

• SSL/TLS-Unterstützung mit Optionen zur Zertifikatsprüfung

• Bereitstellung interaktiver Tools für KI-Assistenten

Die Liste der Tools ist konfigurierbar, sodass Sie auswählen können, welche Tools Sie dem MCP-Client zur Verfügung stellen möchten.

Related MCP server: tickiti-mcp

Voraussetzungen

OTRS-Serverkonfiguration

Bevor Sie diesen MCP-Server verwenden, müssen Sie Ihre OTRS-Instanz konfigurieren:

Schritt 1: OTRS-Admin-Panel aufrufen

• URL: https://your-otrs-server/otrs/index.pl?Action=Admin

• Melden Sie sich mit Ihren Admin-Zugangsdaten an

Schritt 2: Web Services konfigurieren

1. Navigieren Sie zu: Systemadministration → Web Services

2. Erstellen Sie einen Webservice (z. B. „TestInterface") oder verifizieren Sie, dass Sie einen mit den folgenden Operationen haben:

   • ✅ SessionCreate

   • ✅ TicketCreate

   • ✅ TicketGet

   • ✅ TicketSearch

   • ✅ TicketUpdate

   • ✅ TicketHistoryGet

Schritt 3: Notieren Sie Ihre Webservice-URL

Ihre Webservice-URL sollte wie folgt aussehen:

https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/YourWebserviceName

Schritt 4: Benutzerberechtigungen sicherstellen

Stellen Sie sicher, dass Ihr OTRS-Benutzer über entsprechende Berechtigungen verfügt für:

• Erstellen und Aktualisieren von Tickets

• Zugriff auf Konfigurationselemente

• Verwendung der Generic Interface

Verwendung

Docker (empfohlen)

Der einfachste Weg, otrs-mcp mit Claude Desktop auszuführen, ist Docker. Wenn Sie Docker nicht installiert haben, können Sie es von der offiziellen Docker-Website herunterladen.

Verwendung des vorgefertigten Images

Sie können das vorgefertigte Docker-Image aus dem GitHub Container Registry verwenden:

{
  "mcpServers": {
    "otrs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OTRS_BASE_URL=https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface",
        "-e",
        "OTRS_USERNAME=your-username",
        "-e",
        "OTRS_PASSWORD=your-password",
        "-e",
        "OTRS_VERIFY_SSL=false",
        "-e",
        "OTRS_DEFAULT_QUEUE=Raw",
        "-e",
        "OTRS_DEFAULT_STATE=new",
        "-e",
        "OTRS_DEFAULT_PRIORITY=3 normal",
        "ghcr.io/eduardoantoniojunior/otrs-mcp-server:latest"
      ]
    }
  }
}

Lokales Erstellen

Wenn Sie das Image lieber lokal erstellen möchten:

# Clone the repository
git clone https://github.com/eduardoantoniojunior/otrs-mcp-server.git
cd otrs-mcp-server

# Build the Docker image
docker build -t otrs-mcp-server .

# Run the container
docker run --rm -i \
  -e OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface" \
  -e OTRS_USERNAME="your-username" \
  -e OTRS_PASSWORD="your-password" \
  -e OTRS_VERIFY_SSL="false" \
  otrs-mcp-server

Ausführung mit UV

Alternativ können Sie den Server direkt mit UV ausführen. Setzen Sie zunächst Ihre Umgebungsvariablen:

export OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface"
export OTRS_USERNAME="your-username"
export OTRS_PASSWORD="your-password"
export OTRS_VERIFY_SSL="false"
export OTRS_DEFAULT_QUEUE="Raw"
export OTRS_DEFAULT_STATE="new"
export OTRS_DEFAULT_PRIORITY="3 normal"
export OTRS_DEFAULT_TYPE="Unclassified"

Bearbeiten Sie dann Ihre Claude-Desktop-Konfigurationsdatei und fügen Sie die Serverkonfiguration hinzu:

{
  "mcpServers": {
    "otrs": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to otrs-mcp-server directory>",
        "run",
        "src/otrs_mcp/main.py"
      ],
      "env": {
        "OTRS_BASE_URL": "https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface",
        "OTRS_USERNAME": "your-username",
        "OTRS_PASSWORD": "your-password",
        "OTRS_VERIFY_SSL": "false"
      }
    }
  }
}

Hinweis: Wenn Sie Error: spawn uv ENOENT in Claude Desktop sehen, müssen Sie möglicherweise den vollständigen Pfad zu uv angeben oder die Umgebungsvariable NO_UV=1 in der Konfiguration setzen.

Umgebungsvariablen

Entwicklung

Beiträge sind willkommen! Bitte öffnen Sie ein Issue oder reichen Sie einen Pull Request ein, wenn Sie Vorschläge oder Verbesserungen haben.

Dieses Projekt zielt auf Python 3.12 ab (siehe requires-python in pyproject.toml) und ist für den Produktionseinsatz auf dieser Version validiert.

Dieses Projekt verwendet uv zur Verwaltung von Abhängigkeiten. Installieren Sie uv gemäß den Anweisungen für Ihre Plattform:

curl -LsSf https://astral.sh/uv/install.sh | sh

Installieren Sie Python 3.12 (falls nicht vorhanden) und erstellen Sie die virtuelle Umgebung mit den festgelegten Abhängigkeiten:

# Install the interpreter (managed by uv)
uv python install 3.12

# Create the environment and install dependencies from uv.lock
uv sync --python 3.12 --extra dev

Alternativ mit dem klassischen Workflow:

uv venv --python 3.12
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

Testen

Testen Sie Ihre OTRS-Verbindung und API-Funktionalität:

# Set environment variables
export OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface"
export OTRS_USERNAME="your-username"
export OTRS_PASSWORD="your-password"
export OTRS_VERIFY_SSL="false"

# Run connectivity test
uv run python tests/connectivity_test.py

# Run API functionality test
uv run python tests/test_working_api.py

# Run debug diagnostics
uv run python tests/debug_test.py

Das Projekt enthält Testskripte, die helfen, Ihre OTRS-Konfiguration und API-Konnektivität zu überprüfen.

Führen Sie die Tests mit pytest aus:

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

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

Veröffentlichen des Docker-Images

So veröffentlichen Sie das Docker-Image im GitHub Container Registry zur öffentlichen Nutzung:

Voraussetzungen

1. GitHub-Konto mit einem Repository für dieses Projekt

2. GitHub Personal Access Token mit write:packages-Berechtigung

3. Docker lokal installiert

Schritt-für-Schritt-Veröffentlichung

1. GitHub Personal Access Token erstellen:

   • Gehen Sie zu GitHub-Einstellungen → Entwicklereinstellungen → Personal Access Tokens → Tokens (klassisch)

   • Generieren Sie ein neues Token mit write:packages- und read:packages-Berechtigungen

   • Speichern Sie das Token sicher

2. Beim GitHub Container Registry anmelden:

   echo $GITHUB_TOKEN | docker login ghcr.io -u yourusername --password-stdin

3. Image erstellen und taggen:

   # Build the image
   docker build -t otrs-mcp-server .
   
   # Tag for GitHub Container Registry
   docker tag otrs-mcp-server ghcr.io/yourusername/otrs-mcp-server:latest
   docker tag otrs-mcp-server ghcr.io/yourusername/otrs-mcp-server:v0.1.0

4. In das Registry pushen:

   # Push latest tag
   docker push ghcr.io/yourusername/otrs-mcp-server:latest
   
   # Push version tag
   docker push ghcr.io/yourusername/otrs-mcp-server:v0.1.0

5. Paket öffentlich machen (optional):

   • Gehen Sie zu Ihrem GitHub-Repository

   • Navigieren Sie zum Abschnitt „Packages"

   • Klicken Sie auf Ihr Paket

   • Gehen Sie zu „Package settings"

   • Ändern Sie die Sichtbarkeit auf „Public"

Automatisierte Veröffentlichung mit GitHub Actions

Erstellen Sie .github/workflows/docker-publish.yml:

name: Build and Push Docker Image

on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Alternative: Docker Hub

Um stattdessen auf Docker Hub zu veröffentlichen:

# Login to Docker Hub
docker login

# Tag for Docker Hub
docker tag otrs-mcp-server yourusername/otrs-mcp-server:latest
docker tag otrs-mcp-server yourusername/otrs-mcp-server:v0.1.0

# Push to Docker Hub
docker push yourusername/otrs-mcp-server:latest
docker push yourusername/otrs-mcp-server:v0.1.0

Aktualisieren Sie dann die Claude-Desktop-Konfiguration, um Folgendes zu verwenden:

"ghcr.io/yourusername/otrs-mcp-server:latest"

oder

"yourusername/otrs-mcp-server:latest"

Verfügbare Tools

🎫 Ticketverwaltung

• create_ticket – Ein neues Ticket in OTRS erstellen

• get_ticket – Detaillierte Informationen zu einem bestimmten Ticket abrufen

• search_tickets – Tickets anhand verschiedener Kriterien suchen

• update_ticket – Eigenschaften eines vorhandenen Tickets aktualisieren

• get_ticket_history – Den vollständigen Verlauf eines Tickets abrufen

📊 Ressourcen

• otrs://ticket/{ticket_id} – Direkter Zugriff auf Ticketdaten

• otrs://ticket/{ticket_id}/history – Zugriff auf den Ticketverlauf

• otrs://search/tickets – Übersicht über aktuelle Tickets

Fehlerbehebung

Häufige Probleme

1. SSL-Zertifikatsfehler: Setzen Sie OTRS_VERIFY_SSL=false für selbstsignierte Zertifikate

2. HTTP-301-Weiterleitungen: Stellen Sie sicher, dass Sie HTTPS-URLs verwenden, wenn Ihr OTRS-Server HTTP auf HTTPS umleitet

3. Authentifizierungsfehler: Überprüfen Sie Benutzername, Passwort und Webservice-Konfiguration

4. Fehlende Operationen: Stellen Sie sicher, dass Ihr OTRS-Webservice alle erforderlichen Operationen enthält

Debug-Modus

Führen Sie das Debug-Skript aus, um Verbindungsprobleme zu diagnostizieren:

uv run python tests/debug_test.py

Dies testet sowohl HTTP- als auch HTTPS-Verbindungen und liefert detaillierte Fehlerinformationen.

Beispiel für eine funktionierende Konfiguration

Hier ist ein funktionierendes Konfigurationsbeispiel zur Referenz:

# Environment variables
export OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface"
export OTRS_USERNAME="your-username"
export OTRS_PASSWORD="your-password"
export OTRS_VERIFY_SSL="false"
export OTRS_DEFAULT_QUEUE="Raw"
export OTRS_DEFAULT_STATE="new"
export OTRS_DEFAULT_PRIORITY="3 normal"
export OTRS_DEFAULT_TYPE="Unclassified"

OTRS-Webservice-Operationen

Ihr OTRS-Webservice sollte diese Operationen enthalten:

Lizenz

Apache-2.0