i-net HelpDesk MCP Сервер

MCP-сервер, предоставляющий Ticket-Web-API системы i-net HelpDesk в качестве инструментов для любых ИИ-агентов: поиск и чтение тикетов, просмотр шагов обработки, создание новых тикетов и выполнение действий над тикетами (ответить, закрыть, эскалировать …), включая вложения файлов.

Сервер может работать в двух режимах:

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

• Python 3.10 или новее

• i-net HelpDesk с активированным Web API

• Пользователь с правом «Web API» — без этого права сервер отвечает HTTP 403. Какие тикеты видны и какие действия разрешены, определяется ролями этого пользователя.

Related MCP server: tickiti-mcp

Установка

# direkt aus dem Repository ausführen (empfohlen für den Einstieg)
uvx --from git+https://github.com/roddyst/i-net_mcp_server inet-helpdesk-mcp --help

# oder klassisch installieren
pip install git+https://github.com/roddyst/i-net_mcp_server

Для разработки:

git clone https://github.com/roddyst/i-net_mcp_server
cd i-net_mcp_server
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest

Быстрый старт: stdio (локальный агент)

export INET_BASE_URL="https://helpdesk.example.com:9000"
export INET_TOKEN="VGhpcyBpcyBqdXN0IGEgZGVtbyBhY2Nlc3MgdG9rZW4u"
inet-helpdesk-mcp

Конфигурация для Claude Desktop / Claude Code (claude_desktop_config.json или .mcp.json) — дополнительные примеры находятся в examples/:

{
  "mcpServers": {
    "i-net-helpdesk": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/roddyst/i-net_mcp_server", "inet-helpdesk-mcp"],
      "env": {
        "INET_BASE_URL": "https://helpdesk.example.com:9000",
        "INET_TOKEN": "dein-access-token"
      }
    }
  }
}

Вместо токена можно использовать INET_USERNAME и INET_PASSWORD (Basic Auth). Токен отправляется как Authorization: Bearer <token>, как описано в документации i-net.

Быстрый старт: HTTP (централизованный хостинг)

inet-helpdesk-mcp --transport http --host 0.0.0.0 --port 8000 \
                  --base-url https://helpdesk.example.com:9000

Тогда конечная точка находится по адресу http://<host>:8000/mcp. Агент вводит этот URL и отправляет свой токен HelpDesk в заголовке Authorization — именно это и есть процесс «URL + Bearer-токен», сервер передаёт заголовок в HelpDesk. Пример для MCP-клиента, поддерживающего удалённые серверы:

{
  "mcpServers": {
    "i-net-helpdesk": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer dein-access-token" }
    }
  }
}

Без --base-url клиент дополнительно определяет целевую систему через заголовок X-Inet-Base-Url. Это удобно для клиентов с несколькими экземплярами HelpDesk, но открывает сервер как прокси для произвольных адресов — в открытой сети лучше задать фиксированный --base-url (тогда заголовок отключается, если только он не разрешён с помощью --allow-url-header).

Примечание по эксплуатации: Сервер сам не завершает TLS и не аутентифицирует клиентов — вход выполняется в HelpDesk с переданным токеном. Если сервер должен быть доступен за пределами локальной сети, перед ним должен быть обратный прокси с HTTPS.

Инструменты

create_ticket и apply_ticket_action не регистрируются при использовании --read-only — полезно, если агент должен только читать.

ID тикетов принимаются как в числовом виде, так и в закодированной форме, которая используется в темах писем HelpDesk.

Типичный рабочий процесс

1. search_tickets с фразой, например Принтер или Resource:"First Level Support"

2. get_ticket / list_ticket_steps / get_ticket_step для чтения

3. list_ticket_actions, чтобы определить допустимый action_id

4. apply_ticket_action с этим ID — ID различаются в зависимости от тикета, пользователя и статуса тикета, поэтому их нельзя угадывать.

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

ticket_fields, step_fields и action_arguments являются необязательными и обычно не требуются. Если они всё же нужны, действуют правила Web API: ключи должны соответствовать реальным ключам полей (или их локализованным отображаемым именам), значения — строки; значения JSON должны быть закодированы как строка. Примеры из документации i-net:

{
  "ticketextension.dispatchNow": "ALWAYS",           // Ticket sofort disponieren
  "ticketextension.automail": "NO_MAILS_TO_ENDUSER", // keine Auto-Mails an Endanwender
  "processingtimeextension.appointment": "1733875200000", // Wiedervorlage/Termin
  "ticketactionextension.escalate": "{'targetResID':'<GUID>','changeTicketStatus':true}"
}

Неизвестные поля тикета приводят к ошибке, неизвестные аргументы действий молча игнорируются HelpDesk и записываются только в отладочный журнал.

Вложения

Вложения передаются в виде списка, каждый элемент с содержимым либо встроенным в виде Base64 либо как путь в файловой системе сервера:

{
  "text": "Anfrage mit Anhang",
  "attachments": [
    { "name": "screenshot.png", "content_base64": "iVBORw0KGgo…" },
    { "path": "/tmp/protokoll.pdf", "attachment_type": "Attachment" }
  ]
}

path работает только в режиме stdio, где агент и сервер находятся на одной машине; в режимах HTTP он автоматически отключается (и может быть отключён для stdio с помощью --no-local-files). Допустимые значения для attachment_type: Attachment, EmbeddedImage, Signature, Unknown. Максимальный размер файла: 25 МБ.

Конфигурация

Каждая опция доступна как переменная окружения и как параметр командной строки; параметр командной строки имеет приоритет.

Поиск неисправностей

• Сначала вызовите server_info — он показывает базовый URL, метод аутентификации и работает ли тестовый запрос к HelpDesk.

• HTTP 401/403: Срок действия токена истёк или у пользователя отсутствует право «Web API».

• HTTP 404 для тикета: Тикет не существует или не виден этому пользователю; ещё не авторизованные тикеты требуют роли диспетчера.

• Ошибки соединения: Проверьте базовый URL, включая порт (по умолчанию HelpDesk — 9000). Для самоподписанных тестовых систем помогает --no-verify-tls.

• Больше деталей даёт --log-level DEBUG (логи выводятся в stderr).

Замечания по безопасности

• Учётные данные хранятся в переменных окружения или в заголовке Authorization и никогда не логируются.

• Сервер делает только то, что разрешено вошедшему пользователю — проверка прав остаётся на стороне HelpDesk.

• apply_ticket_action и create_ticket изменяют данные и в зависимости от конфигурации могут отправлять электронные письма конечным пользователям. Для тестов рекомендуется аргумент действия "ticketextension.automail": "NEVER" или тестовая система.

• get_ticket по умолчанию возвращает все поля тикета, включая персональные данные — ограничьте с помощью fields.

English summary

MCP server exposing the i-net HelpDesk Ticket Web-API: search, read, create and act on tickets, with attachment support. Run it over stdio (credentials from INET_BASE_URL + INET_TOKEN) or over streamable HTTP, where each client authenticates by sending its own Authorization: Bearer <token> header — and, when no base URL is configured, selects the HelpDesk instance with an X-Inet-Base-Url header. Tools: server_info, search_tickets, get_ticket, list_ticket_actions, list_ticket_steps, get_ticket_step, create_ticket, apply_ticket_action. Start with --read-only to expose the reading tools only.

Лицензия

MIT. Неофициальный продукт i-net software GmbH. Документация Web API: https://docs.inetsoftware.de/helpdesk/help/webapi.ticket/p/ticket-web-api