zendesk-mcp
zendesk-mcp
Un servidor de Model Context Protocol que expone herramientas de lectura y escritura de tickets de Zendesk a Claude Code y otros clientes MCP.
Qué hace
Buscar, listar (paginado) y obtener tickets, comentarios y adjuntos de Zendesk
Crear nuevos tickets y actualizar campos de tickets existentes (incluyendo grupo, estado personalizado y etiquetas)
Publicar respuestas públicas y notas internas
Establecer el estado del ticket y asignar tickets a agentes
Explorar y aplicar vistas y macros
Buscar usuarios, grupos, organizaciones y estados personalizados
Leer y escribir entradas de seguimiento de tiempo
Formatear un ticket como borrador de issue en Markdown para transferirlo a un rastreador (GitLab, GitHub, Jira)
Dos prompts MCP (
analyze-ticket,draft-ticket-response) para análisis de tickets y redacción de respuestas(Opcional) Exponer artículos del Centro de ayuda de Zendesk como recurso MCP
(Opcional) Leer issues / MRs / commits vinculados de GitLab mediante la aplicación Zendesk Git-Zen
Related MCP server: Zendesk MCP Server
Requisitos previos
Python 3.10 o superior
Un cliente OAuth de Zendesk. Un administrador de Zendesk puede crear uno en:
https://<your-subdomain>.zendesk.com/admin/apps-integrations/apis/zendesk-api/oauth_clientsEstablece la URL de redirección ahttp://localhost:8787/callbacky solicita los ámbitosread write.
Instalación
Instala en un virtualenv local del proyecto. Usar un venv mantiene zendesk-mcp y sus dependencias aislados de tu Python del sistema y de otros proyectos, y es la ruta recomendada para todo lo siguiente.
Desde un clon de este repositorio:
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .Para desarrollo (también instala pytest):
.venv/bin/pip install -e ".[dev]"A lo largo de este README, los comandos usan los binarios del venv mediante
.venv/bin/.... Puedes, en su lugar, ejecutarsource .venv/bin/activateuna vez por shell y omitir el prefijo: el resultado es el mismo.
Configuración de OAuth
Ejecuta la configuración interactiva usando el Python del venv:
.venv/bin/python -m zendesk_mcp setupSe te pedirá:
Tu subdominio de Zendesk (p. ej.
acmeparaacme.zendesk.com)El ID de cliente OAuth creado por tu administrador
El secreto del cliente OAuth
(Opcional) Un ID de campo de integración de Git-Zen: consulta Opcional: integración de Git-Zen
(Opcional) Si habilitar el recurso de base de conocimientos del Centro de ayuda: consulta Opcional: base de conocimientos del Centro de ayuda
La configuración abre un navegador para el paso de autorización OAuth y luego escribe un token en ~/.config/zendesk-mcp/config.json (modo 0600).
Si no tienes navegador, la URL se imprime en la terminal: ábrela en cualquier dispositivo, haz clic en Permitir y pega la URL de redirección resultante de nuevo en el prompt.
Caducidad y renovación del token
Los tokens de acceso de Zendesk caducan. Los clientes OAuth creados el 2026-04-30 o después obtienen una vida útil predeterminada de 30 minutos; los clientes más antiguos emiten tokens sin caducidad a menos que se solicite una. La configuración solicita un token de acceso de 24 horas y un token de actualización de 90 días para que el comportamiento sea el mismo en ambos casos, y el servidor renueva el token de acceso automáticamente: antes de que caduque, y de nuevo si Zendesk rechaza un token a mitad de una solicitud.
Para que eso sea posible, el archivo de configuración también almacena refresh_token, expires_at, client_id y client_secret junto al token de acceso. Mantén el archivo en modo 0600; es el mismo nivel de confianza que el propio token de acceso. Si tu cliente OAuth no devuelve un token de actualización, la configuración lo indica y el token se usa tal cual.
Vuelve a ejecutar .venv/bin/python -m zendesk_mcp setup cuando:
el token de actualización caduque (90 días sin uso), o
revoques la concesión OAuth en Zendesk.
En cualquier caso, las herramientas devuelven Zendesk authorization failed: ... Re-run: zendesk-mcp setup en lugar de fallar de forma opaca.
Registro con Claude Code
Registra el servidor MCP usando el Python del venv mediante ruta absoluta. Claude Code lanza el servidor en un shell nuevo que no hereda tu venv activado, por lo que la ruta absoluta es obligatoria: apuntar a un python simple aquí fallará al importar 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_mcpO simplemente escribe la ruta absoluta que quieras:
claude mcp add --scope user zendesk -- /absolute/path/to/zendesk-mcp/.venv/bin/python -m zendesk_mcpLuego añade las herramientas de lectura a permissions.allow en ~/.claude/settings.json para evitar avisos por llamada:
{
"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"
]
}
}Las herramientas de escritura (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) no están intencionadamente en la lista de permitidos predeterminada: Claude te pedirá confirmación en cada llamada.
Herramientas
Tickets
Tool | Qué hace |
| Buscar tickets por estado, prioridad, tipo, asignado, solicitante, etiquetas o palabra clave |
| Listar tickets con paginación y ordenación (page, per_page, sort_by, sort_order) |
| Obtener los metadatos de un ticket |
| Crear un nuevo ticket (asunto, descripción, prioridad/tipo/assignee_id/requester_id/etiquetas/custom_fields opcionales) |
| Actualizar uno o más campos de un ticket existente (status, priority, subject, type, assignee_id, requester_id, group_id, custom_status_id, tags, custom_fields, due_at) |
| Obtener el hilo de conversación de un ticket |
| Listar adjuntos de un ticket |
| Descargar un adjunto a un directorio de caché local |
| Formatear un ticket y su conversación como borrador de issue en Markdown |
| Publicar una respuesta pública en un ticket |
| Publicar una nota interna solo para agentes en un ticket |
| Establecer el estado del ticket ( |
| Asignar un ticket a un agente por correo electrónico o |
Etiquetas
Tool | Qué hace |
| Añadir una etiqueta a un ticket (idempotente) |
| Eliminar una etiqueta de un ticket (idempotente) |
Vistas y macros
Tool | Qué hace |
| Listar todas las vistas activas |
| Obtener las condiciones de filtro y la configuración de ejecución de una vista |
| Obtener los tickets que coinciden actualmente con una vista |
| Listar macros activas con sus acciones |
| Previsualizar qué cambios haría una macro |
| Aplicar una macro a un ticket (aplica cambios de campo y publica cualquier comentario) |
Usuarios, grupos y organizaciones
Tool | Qué hace |
| Buscar usuarios por nombre o correo electrónico |
| Listar todos los grupos activos |
| Listar los miembros de un grupo |
| Obtener una organización incluyendo campos personalizados |
| Listar todos los estados personalizados de tickets y sus IDs |
Seguimiento de tiempo
Tool | Qué hace |
| Leer entradas de seguimiento de tiempo de un ticket |
| Registrar una entrada de tiempo en un ticket |
Integración de Git-Zen
Tool | Qué hace |
| (Solo Git-Zen) Obtener issues / MRs / commits vinculados de GitLab para un ticket |
Prompts
El servidor expone dos prompts MCP que algunos clientes (p. ej. Claude Desktop) muestran como comandos de barra:
Prompt | Argument | Qué hace |
|
| Pide al modelo que obtenga el ticket y produzca un resumen, estado/cronología y puntos clave de interacción |
|
| Pide al modelo que obtenga el ticket y redacte una respuesta orientada al cliente (con un paso de confirmación antes de publicar) |
Opcional: integración de Git-Zen
Si tu instancia de Zendesk usa la aplicación Git-Zen, la herramienta zendesk_get_git_zen_links puede leer su carga útil de campo personalizado. Encuentra el ID de campo personalizado de Git-Zen de tu instancia en Admin → Tickets → Fields (es un ID numérico) y luego establécelo durante .venv/bin/python -m zendesk_mcp setup o edita ~/.config/zendesk-mcp/config.json para añadir:
{
"git_zen_field_id": 12345678901234
}Sin esta configuración, zendesk_get_git_zen_links devuelve un mensaje de "no configurado".
Opcional: base de conocimientos del Centro de ayuda
Si tu instancia de Zendesk tiene un Centro de ayuda publicado, puedes exponer sus secciones y artículos como el recurso MCP zendesk://knowledge-base. El recurso devuelve un único documento JSON que cubre todas las secciones y artículos, con caché de una hora.
Esto es opcional. Habilítalo respondiendo "y" al prompt durante .venv/bin/python -m zendesk_mcp setup, o añadiendo lo siguiente a ~/.config/zendesk-mcp/config.json:
{
"knowledge_base_enabled": true
}Cuando el indicador está ausente o es falso, el recurso no se registra, manteniendo vacía la lista de recursos del servidor para instancias sin un Centro de ayuda.
Desarrollo
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytestLas pruebas se ejecutan en Python 3.10, 3.11 y 3.12 en CI (consulta .github/workflows/test.yml).
Publicación
Incrementa la versión en pyproject.toml, mcpb/pyproject.toml (tanto la versión como el pin zendesk-mcp==), mcpb/manifest.json y server.json (ambos campos), luego haz push de una etiqueta v*. Eso activa .github/workflows/release.yml, que publica en PyPI, empaqueta el paquete MCPB, publica server.json en el Registro MCP y crea la versión de GitHub.
Comprueba que las versiones coincidan antes de etiquetar; de lo contrario, la publicación falla rápidamente:
python3 .github/scripts/check_versions.py 0.1.5Licencia
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.-