zendesk-mcp

Un servidor del Model Context Protocol que expone herramientas de lectura y escritura de tickets de Zendesk a Claude Code y otros clientes MCP.

Qué hace

• Buscar y obtener tickets, comentarios y archivos adjuntos de Zendesk

• Publicar respuestas públicas y notas internas

• Establecer el estado del ticket y asignar tickets a agentes

• Leer y escribir entradas de registro de tiempo

• Formatear un ticket como un borrador de incidencia en Markdown para su traspaso a un gestor de incidencias (GitLab, GitHub, Jira)

• (Opcional) Leer incidencias/MRs/commits de GitLab vinculados a través de la aplicación de Zendesk Git-Zen

Requisitos previos

• Python 3.10 o superior

• Un cliente OAuth de Zendesk. Un administrador de Zendesk puede crear uno en: https://<tu-subdominio>.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 entorno virtual local del proyecto. Usar un venv mantiene zendesk-mcp y sus dependencias aisladas 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 utilizan los binarios del venv a través de .venv/bin/.... Puedes, en su lugar, ejecutar source .venv/bin/activate una vez por sesión 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 solicitará:

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

2. El ID de cliente OAuth creado por tu administrador

3. El secreto de cliente OAuth

4. (Opcional) Un ID de campo de integración Git-Zen — ver Opcional: Integración con Git-Zen

La configuración abre un navegador para el paso de autorización OAuth, 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 Allow (Permitir) y pega la URL de redirección resultante de vuelta en el prompt.

Registrar con Claude Code

Registra el servidor MCP usando el Python del venv mediante la ruta absoluta. Claude Code lanza el servidor en una shell nueva que no hereda tu venv activado, por lo que se requiere la ruta absoluta; apuntar a un python genérico 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 incluye la ruta absoluta que desees:

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 prompts por cada llamada:

{
  "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"
    ]
  }
}

Las herramientas de escritura (zendesk_post_comment, zendesk_post_internal_note, zendesk_set_ticket_status, zendesk_assign_ticket, zendesk_log_time) no están intencionalmente en la lista de permitidos por defecto; Claude te solicitará confirmación por cada llamada.

Herramientas

Opcional: Integración con Git-Zen

Si tu instancia de Zendesk utiliza la aplicación Git-Zen, la herramienta zendesk_get_git_zen_links puede leer su carga útil de campo personalizado. Encuentra el ID del campo personalizado de Git-Zen de tu instancia en Admin → Tickets → Fields (es un ID numérico), luego configúralo durante .venv/bin/python -m zendesk_mcp setup o edita ~/.config/zendesk-mcp/config.json para añadir:

{
  "git_zen_field_id": 12345678901234
}

Sin esto configurado, zendesk_get_git_zen_links devuelve un mensaje de "no configurado".

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 (ver .github/workflows/test.yml).

Licencia

Apache-2.0