zendesk-mcp

Ein Model Context Protocol-Server, der Zendesk-Ticket-Lese- und Schreib-Tools für Claude Code und andere MCP-Clients bereitstellt.

Was es tut

• Suchen und Abrufen von Zendesk-Tickets, Kommentaren und Anhängen

• Veröffentlichen öffentlicher Antworten und interner Notizen

• Festlegen des Ticketstatus und Zuweisen von Tickets an Agenten

• Lesen und Schreiben von Zeiterfassungseinträgen

• Formatieren eines Tickets als Markdown-Issue-Entwurf zur Übergabe an einen Tracker (GitLab, GitHub, Jira)

• (Optional) Lesen verknüpfter GitLab-Issues / MRs / Commits über die Git-Zen-Zendesk-App

Voraussetzungen

• Python 3.10 oder neuer

• Ein Zendesk OAuth-Client. Ein Zendesk-Administrator kann einen unter folgender Adresse erstellen: https://<your-subdomain>.zendesk.com/admin/apps-integrations/apis/zendesk-api/oauth_clients Setzen Sie die Redirect-URL auf http://localhost:8787/callback und fordern Sie die Scopes read write an.

Installation

Installieren Sie es in ein projektlokales Virtualenv. Die Verwendung eines venv hält zendesk-mcp und seine Abhängigkeiten von Ihrem System-Python und anderen Projekten isoliert und ist der empfohlene Weg für alles Folgende.

Von einem Klon dieses Repositorys:

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

Für die Entwicklung (installiert auch pytest):

.venv/bin/pip install -e ".[dev]"

In dieser gesamten README verwenden die Befehle die Binärdateien des venv über .venv/bin/.... Sie können stattdessen einmal pro Shell source .venv/bin/activate ausführen und das Präfix weglassen — das Ergebnis ist dasselbe.

OAuth-Einrichtung

Führen Sie die interaktive Einrichtung mit dem Python des venv aus:

.venv/bin/python -m zendesk_mcp setup

Sie werden nach Folgendem gefragt:

1. Ihrer Zendesk-Subdomain (z. B. acme für acme.zendesk.com)

2. Der von Ihrem Administrator erstellten OAuth-Client-ID

3. Dem OAuth-Client-Secret

4. (Optional) Einer Git-Zen-Integrationsfeld-ID — siehe Optional: Git-Zen-Integration

Die Einrichtung öffnet einen Browser für den OAuth-Autorisierungsschritt und schreibt dann ein Token nach ~/.config/zendesk-mcp/config.json (Modus 0600).

Wenn Sie keinen Browser haben, wird die URL im Terminal ausgegeben — öffnen Sie diese auf einem beliebigen Gerät, klicken Sie auf Allow (Zulassen) und fügen Sie die resultierende Redirect-URL wieder in die Eingabeaufforderung ein.

Registrierung bei Claude Code

Registrieren Sie den MCP-Server mit dem Python des venv über den absoluten Pfad. Claude Code startet den Server in einer neuen Shell, die Ihr aktiviertes venv nicht erbt, daher ist der absolute Pfad erforderlich — ein Verweis auf ein bloßes python hier führt dazu, dass der Import von zendesk_mcp fehlschlägt.

ZENDESK_MCP_DIR="$(pwd)"   # run this from the repo root, after install
claude mcp add --scope user zendesk -- "$ZENDESK_MCP_DIR/.venv/bin/python" -m zendesk_mcp

Oder geben Sie einfach den gewünschten absoluten Pfad direkt an:

claude mcp add --scope user zendesk -- /absolute/path/to/zendesk-mcp/.venv/bin/python -m zendesk_mcp

Fügen Sie dann die Lese-Tools zu permissions.allow in ~/.claude/settings.json hinzu, um Aufforderungen pro Aufruf zu vermeiden:

{
  "permissions": {
    "allow": [
      "mcp__zendesk__zendesk_get_ticket",
      "mcp__zendesk__zendesk_get_comments",
      "mcp__zendesk__zendesk_list_attachments",
      "mcp__zendesk__zendesk_download_attachment",
      "mcp__zendesk__zendesk_search_tickets",
      "mcp__zendesk__zendesk_ticket_to_gitlab_context"
    ]
  }
}

Schreib-Tools (zendesk_post_comment, zendesk_post_internal_note, zendesk_set_ticket_status, zendesk_assign_ticket, zendesk_log_time) sind absichtlich nicht in der Standard-Allow-Liste enthalten — Claude wird Sie pro Aufruf dazu auffordern.

Tools

Optional: Git-Zen-Integration

Wenn Ihre Zendesk-Instanz die Git-Zen-App verwendet, kann das Tool zendesk_get_git_zen_links dessen benutzerdefiniertes Feld-Payload lesen. Suchen Sie die Git-Zen-ID des benutzerdefinierten Felds Ihrer Instanz unter Admin → Tickets → Felder (es ist eine numerische ID) und legen Sie diese entweder während .venv/bin/python -m zendesk_mcp setup fest oder bearbeiten Sie ~/.config/zendesk-mcp/config.json, um Folgendes hinzuzufügen:

{
  "git_zen_field_id": 12345678901234
}

Ohne diese Konfiguration gibt zendesk_get_git_zen_links eine Meldung zurück, dass es nicht konfiguriert ist.

Entwicklung

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Tests werden in der CI auf Python 3.10, 3.11 und 3.12 ausgeführt (siehe .github/workflows/test.yml).

Lizenz

Apache-2.0