zendesk-mcp

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

Что он делает

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

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

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

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

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

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

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

• Python 3.10 или новее

• OAuth-клиент Zendesk. Администратор Zendesk может создать его по адресу: https://<your-subdomain>.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 один раз для каждой оболочки и опустить префикс — результат будет тем же.

Настройка 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

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

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

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

Зарегистрируйте MCP-сервер, используя Python из venv по абсолютному пути. Claude Code запускает сервер в новой оболочке, которая не наследует ваше активированное 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_comments",
      "mcp__zendesk__zendesk_list_attachments",
      "mcp__zendesk__zendesk_download_attachment",
      "mcp__zendesk__zendesk_search_tickets",
      "mcp__zendesk__zendesk_ticket_to_gitlab_context"
    ]
  }
}

Инструменты записи (zendesk_post_comment, zendesk_post_internal_note, zendesk_set_ticket_status, zendesk_assign_ticket, zendesk_log_time) намеренно не включены в список разрешенных по умолчанию — Claude будет запрашивать подтверждение при каждом вызове.

Инструменты

Опционально: интеграция 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".

Разработка

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).

Лицензия

Apache-2.0