Skip to main content
Glama

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_clients Establece la URL de redirección a http://localhost:8787/callback y solicita los ámbitos read 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, ejecutar source .venv/bin/activate una 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 setup

Se te pedirá:

  1. Tu subdominio de Zendesk (p. ej. acme para acme.zendesk.com)

  2. El ID de cliente OAuth creado por tu administrador

  3. El secreto del cliente OAuth

  4. (Opcional) Un ID de campo de integración de Git-Zen: consulta Opcional: integración de Git-Zen

  5. (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_mcp

O simplemente escribe la ruta absoluta que quieras:

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

Luego 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

zendesk_search_tickets

Buscar tickets por estado, prioridad, tipo, asignado, solicitante, etiquetas o palabra clave

zendesk_get_tickets

Listar tickets con paginación y ordenación (page, per_page, sort_by, sort_order)

zendesk_get_ticket

Obtener los metadatos de un ticket

zendesk_create_ticket

Crear un nuevo ticket (asunto, descripción, prioridad/tipo/assignee_id/requester_id/etiquetas/custom_fields opcionales)

zendesk_update_ticket

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)

zendesk_get_comments

Obtener el hilo de conversación de un ticket

zendesk_list_attachments

Listar adjuntos de un ticket

zendesk_download_attachment

Descargar un adjunto a un directorio de caché local

zendesk_ticket_to_gitlab_context

Formatear un ticket y su conversación como borrador de issue en Markdown

zendesk_post_comment

Publicar una respuesta pública en un ticket

zendesk_post_internal_note

Publicar una nota interna solo para agentes en un ticket

zendesk_set_ticket_status

Establecer el estado del ticket (new, open, pending, hold, solved, closed)

zendesk_assign_ticket

Asignar un ticket a un agente por correo electrónico o me

Etiquetas

Tool

Qué hace

zendesk_add_tag

Añadir una etiqueta a un ticket (idempotente)

zendesk_remove_tag

Eliminar una etiqueta de un ticket (idempotente)

Vistas y macros

Tool

Qué hace

zendesk_list_views

Listar todas las vistas activas

zendesk_get_view

Obtener las condiciones de filtro y la configuración de ejecución de una vista

zendesk_get_view_tickets

Obtener los tickets que coinciden actualmente con una vista

zendesk_list_macros

Listar macros activas con sus acciones

zendesk_preview_macro

Previsualizar qué cambios haría una macro

zendesk_apply_macro

Aplicar una macro a un ticket (aplica cambios de campo y publica cualquier comentario)

Usuarios, grupos y organizaciones

Tool

Qué hace

zendesk_search_users

Buscar usuarios por nombre o correo electrónico

zendesk_get_groups

Listar todos los grupos activos

zendesk_get_group_users

Listar los miembros de un grupo

zendesk_get_organization

Obtener una organización incluyendo campos personalizados

zendesk_list_custom_statuses

Listar todos los estados personalizados de tickets y sus IDs

Seguimiento de tiempo

Tool

Qué hace

zendesk_get_time_tracking

Leer entradas de seguimiento de tiempo de un ticket

zendesk_log_time

Registrar una entrada de tiempo en un ticket

Integración de Git-Zen

Tool

Qué hace

zendesk_get_git_zen_links

(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

analyze-ticket

ticket_id

Pide al modelo que obtenga el ticket y produzca un resumen, estado/cronología y puntos clave de interacción

draft-ticket-response

ticket_id

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/pytest

Las 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.5

Licencia

Apache-2.0

Available Tools

29 tools
zendesk_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_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

    A3.7/5.0

    Scored across 29 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers