zendesk-mcp
zendesk-mcp
Ein Model Context Protocol-Server, der Zendesk-Ticket-Lese- und Schreibwerkzeuge für Claude Code und andere MCP-Clients bereitstellt.
Was es tut
Suchen, Auflisten (paginiert) und Abrufen von Zendesk-Tickets, Kommentaren und Anhängen
Neue Tickets erstellen und bestehende Ticketfelder aktualisieren (einschließlich Gruppe, benutzerdefinierter Status und Tags)
Öffentliche Antworten und interne Notizen posten
Ticketstatus setzen und Tickets Agenten zuweisen
Ansichten und Makros durchsuchen und anwenden
Benutzer, Gruppen, Organisationen und benutzerdefinierte Status nachschlagen
Zeiterfassungseinträge lesen und schreiben
Ein Ticket als Markdown-Issue-Entwurf für die Übergabe an einen Tracker (GitLab, GitHub, Jira) formatieren
Zwei MCP-Prompts (
analyze-ticket,draft-ticket-response) für Ticketanalyse und Antwortentwurf(Optional) Zendesk Help Center-Artikel als MCP-Ressource bereitstellen
(Optional) Verknüpfte GitLab-Issues / MRs / Commits über die Git-Zen Zendesk-App lesen
Related MCP server: Zendesk MCP Server
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_clientsSetzen Sie die Weiterleitungs-URL aufhttp://localhost:8787/callbackund fordern Sie die Bereicheread writean.
Installation
Installieren Sie in eine projektspezifische virtuelle Umgebung. Die Verwendung einer 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.
Aus 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 diesem README verwenden die Befehle die Binärdateien der venv über
.venv/bin/.... Sie können stattdessen einmal pro Shellsource .venv/bin/activateausführen und das Präfix weglassen – das Ergebnis ist dasselbe.
OAuth-Einrichtung
Führen Sie die interaktive Einrichtung mit dem Python der venv aus:
.venv/bin/python -m zendesk_mcp setupSie werden aufgefordert, Folgendes anzugeben:
Ihre Zendesk-Subdomain (z.B.
acmefüracme.zendesk.com)Die von Ihrem Administrator erstellte OAuth-Client-ID
Das OAuth-Client-Geheimnis
(Optional) Eine Git-Zen-Integrationsfeld-ID – siehe Optional: Git-Zen-Integration
(Optional) Ob die Help-Center-Wissensdatenbank-Ressource aktiviert werden soll – siehe Optional: Help-Center-Wissensdatenbank
Die Einrichtung öffnet einen Browser für den OAuth-Autorisierungsschritt und schreibt dann ein Token in ~/.config/zendesk-mcp/config.json (Modus 0600).
Wenn Sie keinen Browser haben, wird die URL im Terminal ausgegeben – öffnen Sie sie auf einem beliebigen Gerät, klicken Sie auf Allow und fügen Sie die resultierende Weiterleitungs-URL wieder in die Eingabeaufforderung ein.
Token-Ablauf und -Aktualisierung
Zendesk-Zugriffstokens laufen ab. OAuth-Clients, die am oder nach dem 2026-04-30 erstellt wurden, erhalten eine Standardlebensdauer von 30 Minuten; ältere Clients geben nicht ablaufende Tokens aus, es sei denn, ein Ablauf wird angefordert. Die Einrichtung fordert ein 24-Stunden-Zugriffstoken und ein 90-Tage-Refresh-Token an, sodass das Verhalten in beiden Fällen gleich ist, und der Server erneuert das Zugriffstoken automatisch – bevor es abläuft und erneut, wenn Zendesk ein Token mitten in einer Anfrage ablehnt.
Um das zu ermöglichen, speichert die Konfigurationsdatei neben dem Zugriffstoken auch refresh_token, expires_at, client_id und client_secret. Halten Sie die Datei im Modus 0600; sie hat die gleiche Vertrauensstufe wie das Zugriffstoken selbst. Wenn Ihr OAuth-Client kein Refresh-Token zurückgibt, weist die Einrichtung darauf hin und das Token wird unverändert verwendet.
Führen Sie .venv/bin/python -m zendesk_mcp setup erneut aus, wenn:
das Refresh-Token abläuft (90 Tage ohne Nutzung), oder
Sie die OAuth-Genehmigung in Zendesk widerrufen.
In beiden Fällen geben die Werkzeuge Zendesk authorization failed: ... Re-run: zendesk-mcp setup zurück, anstatt undurchsichtig zu scheitern.
Bei Claude Code registrieren
Registrieren Sie den MCP-Server mit dem Python der venv über den absoluten Pfad. Claude Code startet den Server in einer neuen Shell, die Ihre aktivierte venv nicht erbt, daher ist der absolute Pfad erforderlich – ein Verweis auf ein nacktes python hier führt zu einem Importfehler von zendesk_mcp.
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_mcpOder fügen Sie einfach den gewünschten absoluten Pfad ein:
claude mcp add --scope user zendesk -- /absolute/path/to/zendesk-mcp/.venv/bin/python -m zendesk_mcpFügen Sie dann die Lesewerkzeuge zu permissions.allow in ~/.claude/settings.json hinzu, um Eingabeaufforderungen bei jedem Aufruf zu vermeiden:
{
"permissions": {
"allow": [
"mcp__zendesk__zendesk_get_ticket",
"mcp__zendesk__zendesk_get_tickets",
"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",
"mcp__zendesk__zendesk_list_views",
"mcp__zendesk__zendesk_get_view",
"mcp__zendesk__zendesk_get_view_tickets",
"mcp__zendesk__zendesk_list_macros",
"mcp__zendesk__zendesk_preview_macro",
"mcp__zendesk__zendesk_search_users",
"mcp__zendesk__zendesk_get_groups",
"mcp__zendesk__zendesk_get_group_users",
"mcp__zendesk__zendesk_get_organization",
"mcp__zendesk__zendesk_list_custom_statuses"
]
}
}Schreibwerkzeuge (zendesk_post_comment, zendesk_post_internal_note, zendesk_set_ticket_status, zendesk_assign_ticket, zendesk_create_ticket, zendesk_update_ticket, zendesk_log_time, zendesk_add_tag, zendesk_remove_tag, zendesk_apply_macro) sind absichtlich nicht in der Standard-Allow-Liste – Claude wird Sie bei jedem Aufruf zur Bestätigung auffordern.
Werkzeuge
Tickets
Tool | Was es tut |
| Tickets nach Status, Priorität, Typ, Bearbeiter, Anfragendem, Tags oder Stichwort durchsuchen |
| Tickets mit Paginierung und Sortierung auflisten (page, per_page, sort_by, sort_order) |
| Metadaten eines Tickets abrufen |
| Ein neues Ticket erstellen (Betreff, Beschreibung, optional Priorität/Typ/assignee_id/requester_id/Tags/custom_fields) |
| Ein oder mehrere Felder eines bestehenden Tickets aktualisieren (Status, Priorität, Betreff, Typ, assignee_id, requester_id, group_id, custom_status_id, Tags, custom_fields, due_at) |
| Den Konversationsverlauf eines Tickets abrufen |
| Anhänge eines Tickets auflisten |
| Einen Anhang in ein lokales Cache-Verzeichnis herunterladen |
| Ein Ticket und seine Konversation als Markdown-Issue-Entwurf formatieren |
| Eine öffentliche Antwort auf ein Ticket posten |
| Eine nur für Agenten sichtbare interne Notiz auf einem Ticket posten |
| Ticketstatus setzen ( |
| Ein Ticket einem Agenten per E-Mail oder |
Tags
Tool | Was es tut |
| Ein Tag zu einem Ticket hinzufügen (idempotent) |
| Ein Tag von einem Ticket entfernen (idempotent) |
Ansichten & Makros
Tool | Was es tut |
| Alle aktiven Ansichten auflisten |
| Die Filterbedingungen und Ausführungseinstellungen einer Ansicht abrufen |
| Tickets abrufen, die aktuell einer Ansicht entsprechen |
| Aktive Makros mit ihren Aktionen auflisten |
| Vorschau, welche Änderungen ein Makro vornehmen würde |
| Ein Makro auf ein Ticket anwenden (wendet Feldänderungen an und postet ggf. einen Kommentar) |
Benutzer, Gruppen & Organisationen
Tool | Was es tut |
| Benutzer nach Name oder E-Mail finden |
| Alle aktiven Gruppen auflisten |
| Die Mitglieder einer Gruppe auflisten |
| Eine Organisation einschließlich benutzerdefinierter Felder abrufen |
| Alle benutzerdefinierten Ticketstatus und ihre IDs auflisten |
Zeiterfassung
Tool | Was es tut |
| Zeiterfassungseinträge für ein Ticket lesen |
| Einen Zeiteintrag für ein Ticket protokollieren |
Git-Zen-Integration
Tool | Was es tut |
| (nur Git-Zen) Verknüpfte GitLab-Issues / MRs / Commits für ein Ticket abrufen |
Prompts
Der Server stellt zwei MCP-Prompts bereit, die einige Clients (z.B. Claude Desktop) als Slash-Befehle anzeigen:
Prompt | Argument | Was es tut |
|
| Fordert das Modell auf, das Ticket abzurufen und eine Zusammenfassung, einen Status/Zeitverlauf und wichtige Interaktionspunkte zu erstellen |
|
| Fordert das Modell auf, das Ticket abzurufen und eine kundenorientierte Antwort zu entwerfen (mit einem Bestätigungsschritt vor dem Posten) |
Optional: Git-Zen-Integration
Wenn Ihre Zendesk-Instanz die Git-Zen-App verwendet, kann das Werkzeug zendesk_get_git_zen_links deren benutzerdefiniertes Feld-Payload lesen. Finden Sie die Git-Zen-Benutzerdefinierte-Feld-ID Ihrer Instanz unter Admin → Tickets → Felder (es ist eine numerische ID) und setzen Sie sie entweder während .venv/bin/python -m zendesk_mcp setup 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 „nicht konfiguriert“ zurück.
Optional: Help-Center-Wissensdatenbank
Wenn Ihre Zendesk-Instanz ein veröffentlichtes Help Center hat, können Sie dessen Abschnitte und Artikel als MCP-Ressource zendesk://knowledge-base bereitstellen. Die Ressource gibt ein einzelnes JSON-Dokument zurück, das alle Abschnitte und Artikel abdeckt und für eine Stunde zwischengespeichert wird.
Dies ist optional. Aktivieren Sie es, indem Sie entweder während .venv/bin/python -m zendesk_mcp setup mit „y“ antworten oder Folgendes zu ~/.config/zendesk-mcp/config.json hinzufügen:
{
"knowledge_base_enabled": true
}{"type": "text"}
Wenn das Flag fehlt oder false ist, wird die Ressource nicht registriert, sodass die Ressourcenliste des Servers für Instanzen ohne Help Center leer bleibt.
Entwicklung
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytestTests laufen auf Python 3.10, 3.11 und 3.12 in CI (siehe .github/workflows/test.yml).
Veröffentlichung
Erhöhen Sie die Version in pyproject.toml, mcpb/pyproject.toml (sowohl die Version als auch den zendesk-mcp==-Pin), mcpb/manifest.json und server.json (beide Felder) und pushen Sie dann ein v*-Tag. Das löst .github/workflows/release.yml aus, das auf PyPI veröffentlicht, das MCPB-Bundle packt, server.json an die MCP-Registry veröffentlicht und das GitHub-Release erstellt.
Überprüfen Sie, dass die Versionen übereinstimmen, bevor Sie das Tag setzen — andernfalls schlägt das Release schnell fehl:
python3 .github/scripts/check_versions.py 0.1.5Lizenz
Available Tools
29 toolszendesk_add_tagA
Add a tag to a Zendesk ticket. Idempotent: adding an existing tag returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.
Inputs: tag (required), ticket_id (required). Returns: result
zendesk_apply_macroA
Apply a macro to a Zendesk ticket. Fetches the macro preview, applies field changes, and posts any comment included in the macro. Returns JSON with id, status, tags, applied_changes, comment_added.
Inputs: macro_id (required), ticket_id (required). Returns: result
zendesk_assign_ticketA
Assign a Zendesk ticket to an agent by their email address. Pass 'me' as assignee_email to assign the ticket to yourself (the authenticated user).
Inputs: ticket_id (required), assignee_email (required). Returns: result
zendesk_create_ticketA
Create a new Zendesk ticket. subject and description are required. priority: low/normal/high/urgent. type: problem/incident/question/task. requester_id/assignee_id are user IDs (integers). custom_fields is a list of {id, value} dicts. Returns JSON of the created ticket.
Inputs: subject (required), description (required), tags, type, +4 more. Returns: result
zendesk_download_attachmentA
Download a Zendesk attachment. Obtain attachment_url and filename from zendesk_list_attachments. ticket_id is required for cache organization. Optional dest_dir overrides the default cache location; the file is written there and (for archives) extracted alongside it. Archives return a file list and unpack_dir — read individual files with your normal file tools. PDFs return up to ~500KB of extracted text. Images are base64-encoded.
Inputs: filename (required), ticket_id (required), attachment_url (required), dest_dir. Returns: result
zendesk_get_commentsA
Get all comments (public replies and internal notes) for a Zendesk ticket. Includes attachment metadata but does not download files.
Inputs: ticket_id (required). Returns: result
zendesk_get_git_zen_linksA
Get linked GitLab issues, merge requests, and commits for a Zendesk ticket via the Git-Zen integration. Returns structured lists with state, labels, weight, and direct GitLab links.
Inputs: ticket_id (required). Returns: result
zendesk_get_groupsA
List all active Zendesk groups (excluding deleted). Returns JSON array of {id, name}.
Inputs: no named parameters. Returns: result
zendesk_get_group_usersB
List the members of a Zendesk group. Returns JSON array of {id, name, email}.
Inputs: group_id (required). Returns: result
zendesk_get_organizationB
Fetch a Zendesk organization including its custom fields and tags. Returns JSON with id, name, organization_fields, tags, created_at, updated_at.
Inputs: organization_id (required). Returns: result
zendesk_get_ticketA
Get a Zendesk ticket by ID. Returns ticket fields including status, priority, requester, assignee, tags, and description.
Inputs: ticket_id (required). Returns: result
zendesk_get_ticketsA
List Zendesk tickets with pagination. page: 1-based page number. per_page: max 100. sort_by: created_at, updated_at, priority, or status. sort_order: asc or desc. Returns tickets plus pagination metadata.
Inputs: page, sort_by, per_page, sort_order. Returns: result
zendesk_get_time_trackingA
Get time tracking data for a Zendesk ticket. Returns total time spent and time spent on the last update, in both seconds and human-readable format (e.g. '2h 15m').
Inputs: ticket_id (required). Returns: result
zendesk_get_viewA
Get a Zendesk view's definition including filter conditions and execution settings. Returns JSON with id, title, active, conditions, execution.
Inputs: view_id (required). Returns: result
zendesk_get_view_ticketsB
Get the tickets currently matching a Zendesk view. Returns JSON array of tickets with essential fields.
Inputs: view_id (required). Returns: result
zendesk_list_attachmentsA
List all attachments across all comments for a Zendesk ticket. Returns filename, content type, size, and download URL for each. Use zendesk_download_attachment to fetch file contents.
Inputs: ticket_id (required). Returns: result
zendesk_list_custom_statusesA
List all custom ticket statuses defined in Zendesk. Returns JSON array of {id, agent_label, end_user_label, status_category, active, default}. Use the id when setting custom_status_id on a ticket.
Inputs: no named parameters. Returns: result
zendesk_list_macrosA
List all active Zendesk macros with their actions. Returns JSON array of {id, title, description, actions: [{field, value}]}.
Inputs: no named parameters. Returns: result
zendesk_list_viewsA
List all active Zendesk views. Returns JSON array of {id, title}.
Inputs: no named parameters. Returns: result
zendesk_log_timeA
Log time spent on a Zendesk ticket. Adds seconds to the running total and records it as the last-update time. Returns logged amount and new total in seconds and human-readable format.
Inputs: seconds (required), ticket_id (required). Returns: result
zendesk_post_commentA
Post a public reply on a Zendesk ticket. The reply is visible to the requester. Use for customer-facing responses.
Inputs: body (required), ticket_id (required). Returns: result
zendesk_post_internal_noteA
Post an internal note on a Zendesk ticket. Internal notes are only visible to agents and are not sent to the requester.
Inputs: body (required), ticket_id (required). Returns: result
zendesk_preview_macroA
Preview the effect a macro would have (without applying it). Returns the result payload from Zendesk's apply preview endpoint.
Inputs: macro_id (required). Returns: result
zendesk_remove_tagA
Remove a tag from a Zendesk ticket. Idempotent: removing a tag that isn't present returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.
Inputs: tag (required), ticket_id (required). Returns: result
zendesk_search_ticketsA
Search Zendesk tickets by keyword and/or status. keywords: free-text search (e.g. 'login failure LDAP'). status: new, open, pending, hold, solved, closed — leave empty for all statuses. Returns id, subject, status, requester, assignee, and dates.
Inputs: limit, status, keywords. Returns: result
zendesk_search_usersA
Search Zendesk users by name or email. Returns JSON array of {id, name, email, role}.
Inputs: query (required). Returns: result
zendesk_set_ticket_statusB
Set the status of a Zendesk ticket. Valid statuses: new, open, pending, hold, solved, closed.
Inputs: status (required), ticket_id (required). Returns: result
zendesk_ticket_to_gitlab_contextA
Format a Zendesk ticket and its comments as an issue draft. Returns Markdown with ticket metadata, full conversation, and an empty Steps to Reproduce section. Use this output as the description when creating an issue in your tracker.
Inputs: ticket_id (required). Returns: result
zendesk_update_ticketA
Update one or more fields on a Zendesk ticket. Pass only the fields you want to change. status: new/open/pending/hold/solved/closed. priority: low/normal/high/urgent. type: problem/incident/question/task. assignee_id, requester_id, group_id, custom_status_id are integer IDs. due_at is ISO8601. Returns JSON of the refreshed ticket.
Inputs: ticket_id (required), tags, type, due_at, +8 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 29 tools
Each tool has a clearly distinct purpose, even where operations appear similar (e.g., get_ticket, get_tickets, search_tickets). Descriptions clarify when to use each, and there is no meaningful overlap that would cause an agent to select the wrong tool.
All tools share the 'zendesk_' prefix and mostly follow a verb_noun pattern. There is some mixing between 'get_' and 'list_' for read operations, but overall the conventions are predictable and easy to follow.
With 29 tools, this exceeds the 25-tool threshold for a 'too many' rating. While the scope is broad, the high count makes the surface feel heavy and increases selection complexity, even though each tool is well-scoped individually.
The server covers the full ticket lifecycle including comments, attachments, time tracking, views, and macros. Minor gaps exist such as lack of ticket deletion and user management, but core support workflows are well represented.
Maintenance
Related MCP Connectors
Read tickets, users, orgs, macros and satisfaction ratings; create, update and comment on tickets.
Search and read Zammad tickets, customers and organizations; add notes, replies and ticket updates.
Read tickets, contacts, companies, agents and groups; create, update and reply to tickets.
Work with Enchant help desk tickets: list, read, reply, add notes and labels, manage customers.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Zendesk to manage tickets, retrieve ticket fields, comments, and priority based on SLA, as well as get unsolved tickets by agent name.1-
- FlicenseNot gradedqualityAmaintenanceEnables users to fetch, create, and update Zendesk tickets and comments, analyze tickets and draft responses, and query Help Center articles as a knowledge base.-
- FlicenseNot gradedqualityAmaintenanceEnables integration with Zendesk to retrieve and manage tickets and comments, analyze tickets, draft responses, and access Help Center articles as a knowledge base.-
- FlicenseNot gradedqualityAmaintenanceEnables retrieving and managing Zendesk tickets and comments, accessing Help Center articles as a knowledge base, and using specialized prompts for ticket analysis and response drafting.-