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 (con paginación) 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
• Consultar 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 de 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 Git-Zen de Zendesk

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 en http://localhost:8787/callback y solicita los alcances 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/.... También puedes 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 del 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 conocimiento del Centro de ayuda — consulta Opcional: Base de conocimiento 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 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 renovació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 nuevamente si Zendesk rechaza un token a mitad de una solicitud.

Para que esto 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; tiene el mismo nivel de confianza que el propio token de acceso. Si tu cliente OAuth no devuelve un token de renovació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 renovación caduque (90 días sin uso), o
• revoques la concesión OAuth en Zendesk.

En ambos casos, 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 por ruta absoluta. Claude Code inicia 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 agrega las herramientas de lectura a permissions.allow en ~/.claude/settings.json para evitar solicitudes 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 intencionalmente en la lista de permitidos predeterminada — Claude te pedirá confirmación en cada llamada.

Herramientas

Tickets

Herramienta	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 ordenamiento (página, por_página, ordenar_por, orden_de_ordenamiento)
zendesk_get_ticket	Obtener los metadatos de un ticket
zendesk_create_ticket	Crear un nuevo ticket (asunto, descripción, prioridad/tipo/ID_de_asignado/ID_de_solicitante/etiquetas/campos_personalizados opcionales)
zendesk_update_ticket	Actualizar uno o más campos de un ticket existente (estado, prioridad, asunto, tipo, ID_de_asignado, ID_de_solicitante, ID_de_grupo, ID_de_estado_personalizado, etiquetas, campos_personalizados, fecha_de_vencimiento)
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

Herramienta	Qué hace
zendesk_add_tag	Agregar una etiqueta a un ticket (idempotente)
zendesk_remove_tag	Eliminar una etiqueta de un ticket (idempotente)

Vistas y macros

Herramienta	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 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 campos y publica cualquier comentario)

Usuarios, grupos y organizaciones

Herramienta	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

Herramienta	Qué hace
zendesk_get_time_tracking	Leer entradas de seguimiento de tiempo de un ticket
zendesk_log_time	Registrar una entrada de tiempo contra un ticket

Integración de Git-Zen

Herramienta	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 de MCP que algunos clientes (p. ej. Claude Desktop) muestran como comandos de barra:

Prompt	Argumento	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 → Campos (es un ID numérico), luego establécelo durante .venv/bin/python -m zendesk_mcp setup o edita ~/.config/zendesk-mcp/config.json para agregar:

{
  "git_zen_field_id": 12345678901234
}

Sin esta configuración, zendesk_get_git_zen_links devuelve un mensaje de "no configurado".

Opcional: Base de conocimiento 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, almacenado en caché durante una hora.

Esto es opcional. Habilítalo respondiendo "s" al prompt durante .venv/bin/python -m zendesk_mcp setup, o agregando lo siguiente a ~/.config/zendesk-mcp/config.json:

{
  "knowledge_base_enabled": true
}

Cuando la bandera está ausente o es falsa, el recurso no se registra, manteniendo vacía la lista de recursos del servidor para instancias sin 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 de versiones

Incrementa la versión en pyproject.toml, mcpb/pyproject.toml (tanto la versión como el pin de zendesk-mcp==), mcpb/manifest.json y server.json (ambos campos), luego envía una etiqueta v*. Eso activa .github/workflows/release.yml, que publica en PyPI, empaqueta el bundle MCPB, publica server.json en el Registro MCP y crea la versión de GitHub.

Verifica que las versiones coincidan antes de etiquetar — la publicación falla rápidamente de lo contrario:

python3 .github/scripts/check_versions.py 0.1.5

Licencia

Apache-2.0