zendesk-mcp

Сервер Model Context Protocol, который предоставляет инструменты чтения и записи тикетов Zendesk для Claude Code и других MCP-клиентов.

Что он делает

• Поиск, список (с пагинацией) и получение тикетов Zendesk, комментариев и вложений

• Создание новых тикетов и обновление существующих полей тикетов (включая группу, пользовательский статус и теги)

• Публикация публичных ответов и внутренних заметок

• Установка статуса тикета и назначение тикетов агентам

• Просмотр и применение представлений и макросов

• Поиск пользователей, групп, организаций и пользовательских статусов

• Чтение и запись записей учёта времени

• Форматирование тикета как черновика задачи в Markdown для передачи в трекер (GitLab, GitHub, Jira)

• Два MCP-промпта (analyze-ticket, draft-ticket-response) для анализа тикета и составления ответа

• (Опционально) Предоставление статей Справочного центра Zendesk как MCP-ресурса

• (Опционально) Чтение связанных задач / MR / коммитов GitLab через приложение Git-Zen Zendesk

Related MCP server: Zendesk MCP Server

Предварительные требования

• Python 3.10 или новее

• OAuth-клиент Zendesk. Администратор Zendesk может создать его по адресу: https://<ваш-субдомен>.zendesk.com/admin/apps-integrations/apis/zendesk-api/oauth_clients Установите URL перенаправления http://localhost:8787/callback и запросите области read write.

Установка

Установите в локальный виртуальный окружение проекта. Использование venv изолирует zendesk-mcp и его зависимости от системного Python и других проектов, и это рекомендуемый путь для всего нижеследующего.

Из клона этого репозитория:

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

Для разработки (также устанавливает pytest):

.venv/bin/pip install -e ".[dev]"

В этом README команды используют бинарники venv через .venv/bin/.... Вы можете вместо этого выполнить source .venv/bin/activate один раз в каждом shell и опустить префикс — результат тот же.

Настройка OAuth

Запустите интерактивную настройку, используя Python из venv:

.venv/bin/python -m zendesk_mcp setup

Вам будет предложено:

1. Ваш субдомен Zendesk (например, acme для acme.zendesk.com)

2. ID OAuth-клиента, созданный вашим администратором

3. Секрет OAuth-клиента

4. (Опционально) ID поля интеграции Git-Zen — см. Опционально: интеграция Git-Zen

5. (Опционально) Включить ли ресурс базы знаний Справочного центра — см. Опционально: база знаний Справочного центра

Настройка открывает браузер для шага авторизации OAuth, затем записывает токен в ~/.config/zendesk-mcp/config.json (режим 0600).

Если у вас нет браузера, URL выводится в терминал — откройте его на любом устройстве, нажмите Allow и вставьте полученный URL перенаправления обратно в запрос.

Срок действия токена и обновление

Токены доступа Zendesk истекают. OAuth-клиенты, созданные 2026-04-30 или позже, получают срок действия по умолчанию 30 минут; более старые клиенты выдают бессрочные токены, если не запрошен срок действия. Настройка запрашивает токен доступа на 24 часа и refresh-токен на 90 дней, чтобы поведение было одинаковым в любом случае, и сервер автоматически обновляет токен доступа — до его истечения, а также если Zendesk отклоняет токен в середине запроса.

Чтобы это было возможно, файл конфигурации также хранит refresh_token, expires_at, client_id и client_secret вместе с токеном доступа. Держите файл в режиме 0600; он имеет тот же уровень доверия, что и сам токен доступа. Если ваш OAuth-клиент не возвращает refresh-токен, настройка сообщает об этом, и токен используется как есть.

Повторно запустите .venv/bin/python -m zendesk_mcp setup, когда:

• истекает refresh-токен (90 дней без использования), или

• вы отзываете разрешение OAuth в Zendesk.

В любом случае инструменты возвращают Zendesk authorization failed: ... Re-run: zendesk-mcp setup вместо непрозрачной ошибки.

Регистрация в Claude Code

Зарегистрируйте MCP-сервер, используя Python из venv по абсолютному пути. Claude Code запускает сервер в новом shell, который не наследует ваш активированный venv, поэтому абсолютный путь обязателен — указание голого python здесь приведёт к ошибке импорта 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

Или просто укажите нужный абсолютный путь:

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

Затем добавьте инструменты чтения в permissions.allow в ~/.claude/settings.json, чтобы избежать запросов при каждом вызове:

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

Инструменты записи (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) намеренно не включены в список разрешений по умолчанию — Claude будет запрашивать подтверждение при каждом вызове.

Инструменты

Тикеты

Теги

Представления и макросы

Пользователи, группы и организации

Учёт времени

Интеграция Git-Zen

Промпты

Сервер предоставляет два MCP-промпта, которые некоторые клиенты (например, Claude Desktop) отображают как слэш-команды:

Опционально: интеграция Git-Zen

Если ваш экземпляр Zendesk использует приложение Git-Zen, инструмент zendesk_get_git_zen_links может читать его полезную нагрузку в пользовательском поле. Найдите ID пользовательского поля Git-Zen в вашем экземпляре в разделе Admin → Tickets → Fields (это числовой ID), затем либо укажите его во время .venv/bin/python -m zendesk_mcp setup, либо отредактируйте ~/.config/zendesk-mcp/config.json, добавив:

{
  "git_zen_field_id": 12345678901234
}

Без этой настройки zendesk_get_git_zen_links возвращает сообщение "not configured".

Опционально: база знаний Справочного центра

Если в вашем экземпляре Zendesk опубликован Справочный центр, вы можете предоставить его разделы и статьи как MCP-ресурс zendesk://knowledge-base. Ресурс возвращает один JSON-документ, охватывающий все разделы и статьи, с кэшированием на один час.

Это включается по желанию. Включите его, ответив "y" на запрос во время .venv/bin/python -m zendesk_mcp setup, или добавив следующее в ~/.config/zendesk-mcp/config.json:

{
  "knowledge_base_enabled": true
}

Когда флаг отсутствует или имеет значение false, ресурс не регистрируется, и список ресурсов сервера остаётся пустым для экземпляров без Help Center.

Разработка

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Тесты запускаются на Python 3.10, 3.11 и 3.12 в CI (см. .github/workflows/test.yml).

Публикация релиза

Поднимите версию в pyproject.toml, mcpb/pyproject.toml (и версию, и пин zendesk-mcp==), mcpb/manifest.json и server.json (оба поля), затем запушьте тег v*. Это запускает .github/workflows/release.yml, который публикует в PyPI, упаковывает MCPB-бандл, публикует server.json в MCP Registry и создаёт GitHub-релиз.

Проверьте, что версии совпадают, перед созданием тега — иначе релиз упадёт с явной ошибкой:

python3 .github/scripts/check_versions.py 0.1.5

Лицензия

Apache-2.0