@horuzhenko/mcp-guacamole

MCP-сервер для управления Apache Guacamole через LLM. Предоставляет набор инструментов (tools) для подключения к удаленным рабочим столам, управления вводом и получения скриншотов.

Возможности

• 🔐 Автоматическая аутентификация: Получение токена по логину/паролю
• 🖥️ Управление сессиями: Подключение и отключение от удаленных рабочих столов
• 🖱️ Ввод: Перемещение мыши, клики, ввод текста, комбинации клавиш, прокрутка
• 📸 Скриншоты: Получение снимков экрана в PNG/WebP формате
• ⚡ InputSequencer: Последовательное выполнение операций с задержками
• 🔄 JSON-RPC: Стандартный протокол MCP для взаимодействия с LLM
• 🚀 run_sequence: Batch-инструмент для выполнения множества действий в одном вызове
• ⚙️ Конфигурация: Профили подключения с дефолтными настройками
• 🌍 Переменные окружения: Настройка через переменные окружения
• 💓 Keep-Alive: Автоматическое поддержание активности соединений
• ⏰ TTL: Автоматическое отключение неактивных сессий

Установка

pnpm add @horuzhenko/mcp-guacamole

Или для глобальной установки:

npm install -g @horuzhenko/mcp-guacamole

Конфигурация через переменные окружения

Сервер поддерживает настройку через переменные окружения, что упрощает развертывание в различных средах:

| Переменная | Описание | Значение по умолчанию | |------------|----------|----------------------| | MCP_GUAC_BASE_URL | URL сервера Guacamole | http://localhost:8080/guacamole | | MCP_GUAC_USERNAME | Имя пользователя | guacadmin | | MCP_GUAC_PASSWORD | Пароль | guacadmin | | MCP_GUAC_WIDTH | Ширина экрана | 1280 | | MCP_GUAC_HEIGHT | Высота экрана | 800 | | MCP_GUAC_DPI | DPI экрана | 96 | | MCP_GUAC_CONNECTION_ID | ID соединения | vnc-ubuntu | | MCP_GUAC_DATASOURCE | Источник данных | (не задан) |

Пример использования с переменными окружения

# Настройка переменных окружения
export MCP_GUAC_BASE_URL="http://my-guacamole:8080/guacamole"
export MCP_GUAC_USERNAME="admin"
export MCP_GUAC_PASSWORD="mypassword"
export MCP_GUAC_WIDTH="1920"
export MCP_GUAC_HEIGHT="1080"
export MCP_GUAC_CONNECTION_ID="my-vnc-connection"

# Запуск сервера
npx @horuzhenko/mcp-guacamole

При использовании переменных окружения можно подключаться с минимальными параметрами:

{
  "name": "connect",
  "arguments": {
    "auth": {}
  }
}

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

Режимы работы

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

Постоянно работающий сервер для эффективного взаимодействия с LLM:

# Запуск демона
npx @horuzhenko/mcp-guacamole daemon start

# Остановка демона
npx @horuzhenko/mcp-guacamole daemon stop

# Статус демона
npx @horuzhenko/mcp-guacamole daemon status

Преимущества демона:

• ✅ Сохранение сессий между запросами
• ✅ Быстрый отклик (~10-50ms vs ~500-2000ms)
• ✅ Один процесс вместо множества
• ✅ Упрощенная интеграция с LLM
• ✅ Keep-Alive и TTL управление сессиями

Подробнее: DAEMON.md

📡 Stdio режим (совместимость)

Традиционный режим для совместимости с существующими интеграциями:

# Как исполняемый файл
npx @horuzhenko/mcp-guacamole

# Или через Node.js
node node_modules/@horuzhenko/mcp-guacamole/dist/server.js

CLI инструмент

Для удобного тестирования и взаимодействия с сервером используйте отдельный CLI пакет:

# Установка CLI
pnpm add @horuzhenko/mcp-guac

# Использование
npx mcp-guac list-tools
npx mcp-guac connect --base-url http://localhost:8080/guacamole --username admin --password secret

Подробнее: @horuzhenko/mcp-guac

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

connect

Подключение к удаленному рабочему столу

Параметры:

{
  "auth": {
    "baseUrl": "http://guacamole-server:8080/guacamole",
    "username": "admin",
    "password": "password",
    "token": "optional-existing-token"
  },
  "display": {
    "width": 1024,
    "height": 768,
    "dpi": 96
  },
  "connectionId": "optional-connection-id",
  "datasource": "mysql"
}

Результат:

{
  "sessionId": "uuid",
  "connectionId": "1",
  "remoteDisplay": { "width": 1024, "height": 768, "dpi": 96 },
  "capabilities": { "absolutePointer": true, "clipboard": true },
  "state": "READY"
}

disconnect

Отключение от сессии

Параметры:

{
  "sessionId": "session-uuid"
}

mouse_move

Перемещение курсора мыши

Параметры:

{
  "sessionId": "session-uuid",
  "x": 100,
  "y": 200
}

mouse_click

Клик мыши (поддерживает двойной клик)

Параметры:

{
  "sessionId": "session-uuid",
  "x": 100,
  "y": 200,
  "button": "left",
  "count": 1
}

scroll

Прокрутка

Параметры:

{
  "sessionId": "session-uuid",
  "x": 300,
  "y": 300,
  "deltaY": -120
}

key_combo

Комбинация клавиш

Параметры:

{
  "sessionId": "session-uuid",
  "keys": ["Ctrl", "c"]
}

type_text

Ввод текста

Параметры:

{
  "sessionId": "session-uuid",
  "text": "Hello, World!"
}

screenshot

Получение скриншота

Параметры:

{
  "sessionId": "session-uuid",
  "format": "png",
  "quality": 90
}

Результат:

{
  "format": "png",
  "width": 1024,
  "height": 768,
  "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "ts": 1234567890
}

run_sequence

Выполнение последовательности действий в одном вызове

Параметры:

{
  "sessionId": "session-uuid",
  "steps": [
    { "move": { "x": 100, "y": 100 } },
    { "wait": 500 },
    { "click": { "x": 100, "y": 100, "button": "left" } },
    { "type": { "text": "Hello!" } },
    { "key": { "keys": ["Enter"] } },
    { "screenshot": { "format": "webp", "quality": 80 } }
  ]
}

Подробнее: RUN_SEQUENCE.md

Пример использования

import { spawn } from 'child_process';

// Запуск MCP-сервера
const server = spawn('node', ['packages/mcp-guacamole/dist/server.js'], {
  stdio: ['pipe', 'pipe', 'inherit']
});

// JSON-RPC запрос на подключение
const connectRequest = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'connect',
    arguments: {
      auth: {
        baseUrl: 'http://192.168.1.100:8080/guacamole',
        username: 'guacadmin',
        password: 'guacadmin'
      },
      display: { width: 1024, height: 768 }
    }
  }
};

server.stdin.write(JSON.stringify(connectRequest) + '\n');

server.stdout.on('data', (data) => {
  const response = JSON.parse(data.toString());
  console.log('Ответ сервера:', response);
});

Архитектура

┌─────────────────┐    JSON-RPC    ┌─────────────────┐
│       LLM       │ ◄─────────────► │  MCP-сервер     │
└─────────────────┘                └─────────────────┘
                                            │
                                            ▼
                                   ┌─────────────────┐
                                   │ InputSequencer  │
                                   └─────────────────┘
                                            │
                                            ▼
                                   ┌─────────────────┐
                                   │   GuacAdapter   │
                                   └─────────────────┘
                                            │
                                            ▼
                                   ┌─────────────────┐
                                   │ Apache Guacamole│
                                   └─────────────────┘

Особенности

InputSequencer

Все операции ввода (кроме скриншотов) выполняются через InputSequencer, который:

• Гарантирует последовательное выполнение операций
• Добавляет реалистичные задержки между действиями
• Разбивает сложные операции (например, клик = move → mousedown → mouseup)
• Предотвращает гонку состояний

Автоматическая аутентификация

Сервер автоматически:

• Получает токен аутентификации по логину/паролю
• Обнаруживает доступные соединения
• Выбирает подходящее соединение (по ID или первое доступное)

Обработка ошибок

• Валидация всех входных параметров через Zod схемы
• Корректная обработка ошибок WebSocket соединения
• Автоматическая очистка ресурсов при отключении

Разработка

# Сборка
pnpm build

# Разработка с автоматической пересборкой
pnpm dev

# Тестирование
pnpm test

# Запуск демо-клиента
cd examples && pnpm mcp-client-demo

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

MCP Guacamole поддерживает конфигурационные файлы для настройки профилей подключения, keep-alive и TTL параметров.

Подробнее: CONFIGURATION.md

Требования

• Node.js 18+
• Apache Guacamole сервер
• Доступ к Guacamole API

Лицензия

MIT