OTRS MCP Server

Сервер Model Context Protocol (MCP) для интеграции с API OTRS (Open Ticket Request System).

Он обеспечивает доступ к управлению заявками OTRS через стандартизированные интерфейсы MCP, позволяя ИИ-ассистентам создавать, искать и управлять заявками.

Возможности

• Создание, чтение, обновление и поиск заявок

• Доступ к истории заявок и подробной информации

• Настраиваемые значения по умолчанию для заявок

• Поддержка контейнеризации Docker

• Поддержка SSL/TLS с возможностями проверки сертификатов

• Предоставление интерактивных инструментов для ИИ-ассистентов

Список инструментов настраивается, поэтому вы можете выбрать, какие инструменты сделать доступными для MCP-клиента.

Related MCP server: tickiti-mcp

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

Конфигурация сервера OTRS

Перед использованием этого MCP-сервера необходимо настроить ваш экземпляр OTRS:

Шаг 1: Доступ к панели администратора OTRS

• URL: https://your-otrs-server/otrs/index.pl?Action=Admin

• Войдите, используя свои административные учетные данные.

Шаг 2: Настройка веб-сервисов

1. Перейдите в: Системное администрирование → Веб-сервисы

2. Создайте или убедитесь, что у вас есть веб-сервис (например, "TestInterface") со следующими операциями:

   • ✅ SessionCreate

   • ✅ TicketCreate

   • ✅ TicketGet

   • ✅ TicketSearch

   • ✅ TicketUpdate

   • ✅ TicketHistoryGet

Шаг 3: Запишите URL вашего веб-сервиса

URL вашего веб-сервиса должен выглядеть так:

https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/YourWebserviceName

Шаг 4: Убедитесь в наличии разрешений пользователя

Убедитесь, что ваш пользователь OTRS имеет соответствующие разрешения для:

• Создания и обновления заявок

• Доступа к элементам конфигурации

• Использования Generic Interface

Использование

Docker (рекомендуется)

Самый простой способ запустить otrs-mcp с Claude Desktop — использовать Docker. Если у вас не установлен Docker, вы можете скачать его с официального сайта Docker.

Использование готового образа

Вы можете использовать готовый Docker-образ из GitHub Container Registry:

{
  "mcpServers": {
    "otrs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OTRS_BASE_URL=https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface",
        "-e",
        "OTRS_USERNAME=your-username",
        "-e",
        "OTRS_PASSWORD=your-password",
        "-e",
        "OTRS_VERIFY_SSL=false",
        "-e",
        "OTRS_DEFAULT_QUEUE=Raw",
        "-e",
        "OTRS_DEFAULT_STATE=new",
        "-e",
        "OTRS_DEFAULT_PRIORITY=3 normal",
        "ghcr.io/eduardoantoniojunior/otrs-mcp-server:latest"
      ]
    }
  }
}

Сборка локально

Если вы предпочитаете собрать образ локально:

# Clone the repository
git clone https://github.com/eduardoantoniojunior/otrs-mcp-server.git
cd otrs-mcp-server

# Build the Docker image
docker build -t otrs-mcp-server .

# Run the container
docker run --rm -i \
  -e OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface" \
  -e OTRS_USERNAME="your-username" \
  -e OTRS_PASSWORD="your-password" \
  -e OTRS_VERIFY_SSL="false" \
  otrs-mcp-server

Запуск с помощью UV

В качестве альтернативы вы можете запустить сервер напрямую с помощью UV. Сначала задайте переменные окружения:

export OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface"
export OTRS_USERNAME="your-username"
export OTRS_PASSWORD="your-password"
export OTRS_VERIFY_SSL="false"
export OTRS_DEFAULT_QUEUE="Raw"
export OTRS_DEFAULT_STATE="new"
export OTRS_DEFAULT_PRIORITY="3 normal"
export OTRS_DEFAULT_TYPE="Unclassified"

Затем отредактируйте файл конфигурации Claude Desktop и добавьте конфигурацию сервера:

{
  "mcpServers": {
    "otrs": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to otrs-mcp-server directory>",
        "run",
        "src/otrs_mcp/main.py"
      ],
      "env": {
        "OTRS_BASE_URL": "https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface",
        "OTRS_USERNAME": "your-username",
        "OTRS_PASSWORD": "your-password",
        "OTRS_VERIFY_SSL": "false"
      }
    }
  }
}

Примечание: если вы видите Error: spawn uv ENOENT в Claude Desktop, возможно, вам потребуется указать полный путь к uv или установить переменную окружения NO_UV=1 в конфигурации.

Переменные окружения

Разработка

Вклад приветствуется! Пожалуйста, откройте issue или отправьте pull request, если у вас есть предложения или улучшения.

Этот проект нацелен на Python 3.12 (см. requires-python в pyproject.toml) и проверен для производственного использования на этой версии.

Этот проект использует uv для управления зависимостями. Установите uv, следуя инструкциям для вашей платформы:

curl -LsSf https://astral.sh/uv/install.sh | sh

Установите Python 3.12 (если он у вас не установлен) и создайте виртуальное окружение с зафиксированными зависимостями:

# Install the interpreter (managed by uv)
uv python install 3.12

# Create the environment and install dependencies from uv.lock
uv sync --python 3.12 --extra dev

В качестве альтернативы, используя классический рабочий процесс:

uv venv --python 3.12
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

Тестирование

Проверьте ваше подключение к OTRS и функциональность API:

# Set environment variables
export OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface"
export OTRS_USERNAME="your-username"
export OTRS_PASSWORD="your-password"
export OTRS_VERIFY_SSL="false"

# Run connectivity test
uv run python tests/connectivity_test.py

# Run API functionality test
uv run python tests/test_working_api.py

# Run debug diagnostics
uv run python tests/debug_test.py

Проект включает тестовые скрипты, которые помогают проверить вашу конфигурацию OTRS и подключение к API.

Запустите тесты с помощью pytest:

# Install development dependencies
uv pip install -e ".[dev]"

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

Публикация Docker-образа

Чтобы опубликовать Docker-образ в GitHub Container Registry для публичного использования:

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

1. Учетная запись GitHub с репозиторием для этого проекта

2. Персональный токен доступа GitHub с разрешением write:packages

3. Docker, установленный локально

Пошаговая публикация

1. Создайте персональный токен доступа GitHub:

   • Перейдите в Настройки GitHub → Настройки разработчика → Персональные токены доступа → Токены (классические)

   • Создайте новый токен с разрешениями write:packages и read:packages

   • Сохраните токен в безопасном месте

2. Войдите в GitHub Container Registry:

   echo $GITHUB_TOKEN | docker login ghcr.io -u yourusername --password-stdin

3. Соберите и пометьте образ:

   # Build the image
   docker build -t otrs-mcp-server .
   
   # Tag for GitHub Container Registry
   docker tag otrs-mcp-server ghcr.io/yourusername/otrs-mcp-server:latest
   docker tag otrs-mcp-server ghcr.io/yourusername/otrs-mcp-server:v0.1.0

4. Отправьте в реестр:

   # Push latest tag
   docker push ghcr.io/yourusername/otrs-mcp-server:latest
   
   # Push version tag
   docker push ghcr.io/yourusername/otrs-mcp-server:v0.1.0

5. Сделайте пакет публичным (необязательно):

   • Перейдите в свой репозиторий GitHub

   • Перейдите в раздел Packages

   • Нажмите на свой пакет

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

   • Измените видимость на Public

Автоматическая публикация с помощью GitHub Actions

Создайте .github/workflows/docker-publish.yml:

name: Build and Push Docker Image

on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Альтернатива: Docker Hub

Чтобы опубликовать в Docker Hub вместо этого:

# Login to Docker Hub
docker login

# Tag for Docker Hub
docker tag otrs-mcp-server yourusername/otrs-mcp-server:latest
docker tag otrs-mcp-server yourusername/otrs-mcp-server:v0.1.0

# Push to Docker Hub
docker push yourusername/otrs-mcp-server:latest
docker push yourusername/otrs-mcp-server:v0.1.0

Затем обновите конфигурацию Claude Desktop, чтобы использовать:

"ghcr.io/yourusername/otrs-mcp-server:latest"

или

"yourusername/otrs-mcp-server:latest"

Доступные инструменты

🎫 Управление заявками

• create_ticket — Создать новую заявку в OTRS

• get_ticket — Получить подробную информацию о конкретной заявке

• search_tickets — Искать заявки по различным критериям

• update_ticket — Обновить свойства существующей заявки

• get_ticket_history — Получить полную историю заявки

📊 Ресурсы

• otrs://ticket/{ticket_id} — Прямой доступ к данным заявки

• otrs://ticket/{ticket_id}/history — Доступ к истории заявки

• otrs://search/tickets — Обзор последних заявок

Устранение неполадок

Частые проблемы

1. Ошибки SSL-сертификата: Установите OTRS_VERIFY_SSL=false для самоподписанных сертификатов

2. HTTP 301 редиректы: Убедитесь, что вы используете HTTPS-URL, если ваш сервер OTRS перенаправляет HTTP на HTTPS

3. Сбои аутентификации: Проверьте ваше имя пользователя, пароль и конфигурацию веб-сервиса

4. Отсутствующие операции: Убедитесь, что ваш веб-сервис OTRS включает все необходимые операции

Режим отладки

Запустите отладочный скрипт для диагностики проблем с подключением:

uv run python tests/debug_test.py

Это проверит как HTTP, так и HTTPS подключения и предоставит подробную информацию об ошибках.

Пример рабочей конфигурации

Для справки, вот пример рабочей конфигурации:

# Environment variables
export OTRS_BASE_URL="https://your-otrs-server/otrs/nph-genericinterface.pl/Webservice/TestInterface"
export OTRS_USERNAME="your-username"
export OTRS_PASSWORD="your-password"
export OTRS_VERIFY_SSL="false"
export OTRS_DEFAULT_QUEUE="Raw"
export OTRS_DEFAULT_STATE="new"
export OTRS_DEFAULT_PRIORITY="3 normal"
export OTRS_DEFAULT_TYPE="Unclassified"

Операции веб-сервиса OTRS

Ваш веб-сервис OTRS должен включать следующие операции:

Лицензия

Apache-2.0