MCP RUVDS

MCP-сервер для создания и управления VPS в RUVDS через API v2. Предоставляет инструменты (tools) для Cursor и других MCP-клиентов: список серверов, каталог (дата-центры, тарифы, ОС), создание/изменение VPS, баланс, действия, SSH-ключи, уведомления, платежи.

Быстрый старт

cp .env.example .env   # указать RUVDS_TOKEN
npm install && npm run build

Подключить сервер в настройках MCP Cursor (см. раздел Подключение в Cursor). После этого в чате с ИИ доступны инструменты ruvds_*.

Related MCP server: Hetzner Cloud MCP Server — Cloud API + SSH management (60 tools)

Требования

• Node.js ≥ 18

• Токен API RUVDS (Bearer) из настроек аккаунта (раздел «Настройки» → API)

Установка

npm install

Настройка

Скопируйте .env.example в .env и укажите токен:

cp .env.example .env
# Отредактируйте .env: RUVDS_TOKEN=ваш_токен

Токен должен иметь нужные права:

• read — список серверов, каталог, баланс, действия, уведомления, платежи, SSH-ключи

• write — создание/изменение серверов, команды (power_on/off, reboot, shutdown), создание SSH-ключей

• remove — удаление серверов и SSH-ключей (при необходимости выдаётся в ЛК RUVDS)

Запуск

• Разработка: npm run dev

• Сборка: npm run build

• Запуск: npm start (или node dist/index.js)

Сервер работает по stdio: клиент (Cursor и др.) запускает процесс и общается через stdin/stdout.

Docker

Сборка образа:

docker build -t mcp-ruvds:latest .

Проверка образа

1. Быстрый запуск (контейнер ждёт ввода по stdio; выход — Ctrl+C):

docker run -i --rm -e RUVDS_TOKEN=ваш_токен mcp-ruvds:latest

Если токен не задан, сервер всё равно стартует, но вызовы к API будут возвращать ошибку.

2. Полная проверка (initialize + tools/list + опционально вызов API):

# без токена — только список инструментов
npm run test:mcp:docker

# с токеном — плюс вызов ruvds_list_datacenters
export RUVDS_TOKEN=ваш_токен
npm run test:mcp:docker

Контейнер при работе с Cursor запускает сам Cursor по мере обращения к MCP.

Подключение в Cursor

Cursor подключается к MCP по stdio: запускает процесс (или контейнер) и передаёт токен через переменные окружения.

Куда вписать настройки

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json

• Windows: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json

• Linux: ~/.config/Cursor/User/globalStorage/cursor.mcp/mcp.json

Либо: Cursor → Settings → MCP и добавить сервер в конфиг.

Вариант 1: запуск без Docker (Node.js на хосте)

В конфиге MCP добавьте блок ruvds (путь к проекту замените на свой):

{
  "mcpServers": {
    "ruvds": {
      "command": "node",
      "args": ["/полный/путь/к/mcp_ruvds.com/dist/index.js"],
      "env": {
        "RUVDS_TOKEN": "ваш_токен_из_ruvds"
      }
    }
  }
}

Перед этим выполните в каталоге проекта:

cd /полный/путь/к/mcp_ruvds.com
npm install
npm run build

Токен можно не хранить в конфиге: задайте переменную окружения в системе и в блоке ruvds укажите только "env": {} или не указывайте env — Cursor передаст переменные процесса в MCP.

Вариант 2: запуск через Docker

Соберите образ один раз:

cd /полный/путь/к/mcp_ruvds.com
docker build -t mcp-ruvds:latest .

В конфиге MCP добавьте:

{
  "mcpServers": {
    "ruvds": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "RUVDS_TOKEN",
        "mcp-ruvds:latest"
      ],
      "env": {
        "RUVDS_TOKEN": "ваш_токен_из_ruvds"
      }
    }
  }
}

• -i — держит stdin открытым для протокола MCP.

• --rm — удаляет контейнер после завершения.

• -e RUVDS_TOKEN — пробрасывает переменную из окружения Cursor в контейнер; значение задаётся в env.RUVDS_TOKEN.

Если RUVDS_TOKEN уже задан в системе и Cursor наследует окружение, можно оставить только проброс в контейнер:

"ruvds": {
  "command": "docker",
  "args": ["run", "-i", "--rm", "-e", "RUVDS_TOKEN", "mcp-ruvds:latest"]
}

Проверка в Cursor

После сохранения конфига перезапустите Cursor или перезагрузите MCP. В чате с AI должны появиться инструменты RUVDS (например, ruvds_list_servers, ruvds_list_datacenters). Можно написать: «Покажи список моих серверов в RUVDS» или «Какие дата-центры есть в RUVDS?».

Инструменты (Tools)

Операции оплаты (продление с баланса) в текущей версии не реализованы.

Параметры API: datacenter, tariff_id, drive_tariff_id, os_id — числовые ID из каталога (ruvds_list_datacenters, ruvds_list_tariffs, ruvds_list_os). payment_period: 1–5 (обычно 1 = 1 мес, 3 = 3 мес, 5 = 12 мес со скидками; точные скидки в ruvds_list_tariffs → payment_period_discount).

Структура проекта

• src/index.ts — точка входа, MCP-сервер, stdio-транспорт, регистрация инструментов.

• src/tools/ — инструменты по группам: servers, catalog, balance, actions, ssh-keys, notifications, payments.

• src/ruvds/ — клиент HTTP (client.ts), обёртки API v2 (api.ts), типы (types.ts).

• Подробно: docs/ARCHITECTURE.md — поток данных, как добавить инструмент, соглашения API.

Для разработчиков и ИИ

Чтобы быстро разобраться и внести изменения:

1. Документация — README (этот файл), docs/ARCHITECTURE.md. API: OpenAPI RUVDS.

2. Добавить инструмент: реализовать вызов API в src/ruvds/api.ts при необходимости; в src/tools/*.ts зарегистрировать server.tool("ruvds_<name>", zodSchema, handler); возвращать jsonContent(result) или handleError(e); обновить таблицу инструментов в README.

3. Токен: обязателен для вызовов API; задаётся в RUVDS_TOKEN (env или конфиг MCP). Ошибка 401 — неверный или отсутствующий токен.

4. Проверка: npm run build && npm run test:mcp; с токеном дополнительно вызывается ruvds_list_datacenters.

Документация API

• RUVDS API v2 OpenAPI

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

Лицензия

MIT