@iflow-mcp/trackline-mcp-remnawave

v1.0.0

Published

7 days ago

MCP server for Remnawave proxy management panel

0High
0Medium
0Low

chatflowdev

qystart

mcp remnawave vpn proxy xray

mcp-remnawave

English | Русский

MCP Server for Remnawave Panel

MCP server (Model Context Protocol) providing LLM clients (Claude Desktop, Cursor, Windsurf, etc.) with tools to manage a Remnawave VPN panel.

Features

51 tools — full management of users, nodes, hosts, subscriptions, squads, HWID devices, and system
3 resources — real-time panel stats, node status, health checks
5 prompts — guided workflows for common tasks
Readonly mode — restrict to read-only operations for safe monitoring
Caddy support — X-Api-Key header for panels behind Caddy with custom path
Type-safe — built on @remnawave/backend-contract for API route validation
stdio transport — works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client

Requirements

Node.js >= 22
Remnawave panel with API token (Settings > API Tokens)

Installation

git clone https://github.com/TrackLine/mcp-remnawave.git
cd mcp-remnawave 
npm install
npm run build

Configuration

Create a .env file or pass environment variables:

| Variable | Required | Description | |----------|----------|-------------| | REMNAWAVE_BASE_URL | Yes | Panel URL (e.g. https://vpn.example.com) | | REMNAWAVE_API_TOKEN | Yes | API token from panel settings | | REMNAWAVE_API_KEY | No | API key for Caddy reverse proxy authentication | | REMNAWAVE_READONLY | No | Set to true to enable readonly mode |

REMNAWAVE_BASE_URL=https://vpn.example.com
REMNAWAVE_API_TOKEN=your-api-token-here

Caddy with Custom Path

If your Remnawave panel is deployed behind Caddy with a custom path and API key protection, set the base URL to include the custom path and provide the API key:

REMNAWAVE_BASE_URL=https://example.com/your-secret-path/api
REMNAWAVE_API_KEY=your-caddy-api-key

The X-Api-Key header will be added to every request automatically.

Readonly Mode

Set REMNAWAVE_READONLY=true to disable all write operations (create, update, delete, enable, disable, restart, revoke, reset). Only read/list tools will be registered.

Useful for monitoring dashboards or shared environments where you want to prevent accidental changes.

In readonly mode, the available tools are reduced from 51 to 21:

| Category | Available tools | |----------|----------------| | Users | users_list, users_get, users_get_by_username, users_get_by_short_uuid | | Nodes | nodes_list, nodes_get | | Hosts | hosts_list, hosts_get | | System | all 8 tools (read-only by nature) | | Subscriptions | all 5 tools (read-only by nature) | | Config Profiles | all 2 tools (read-only by nature) | | Squads | squads_list | | HWID | hwid_devices_list |

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "remnawave": {
      "command": "node",
      "args": ["/absolute/path/to/remnawave-mcp/dist/index.js"],
      "env": {
        "REMNAWAVE_BASE_URL": "https://vpn.example.com",
        "REMNAWAVE_API_TOKEN": "your-api-token-here",
        "REMNAWAVE_API_KEY": "your-caddy-api-key",
        "REMNAWAVE_READONLY": "false"
      }
    }
  }
}

Usage with Cursor / Windsurf

Add to .cursor/mcp.json or .windsurf/mcp.json in your project:

{
  "mcpServers": {
    "remnawave": {
      "command": "node",
      "args": ["/absolute/path/to/remnawave-mcp/dist/index.js"],
      "env": {
        "REMNAWAVE_BASE_URL": "https://vpn.example.com",
        "REMNAWAVE_API_TOKEN": "your-api-token-here",
        "REMNAWAVE_API_KEY": "your-caddy-api-key",
        "REMNAWAVE_READONLY": "false"
      }
    }
  }
}

Docker

npm run build
docker compose up -d

Environment variables are passed via .env file or docker-compose.yml.

Available Tools

Users (11 tools)

| Tool | Description | Mode | |------|-------------|------| | users_list | List all users with pagination | read | | users_get | Get user by UUID | read | | users_get_by_username | Get user by username | read | | users_get_by_short_uuid | Get user by short UUID | read | | users_create | Create a new user | write | | users_update | Update user settings | write | | users_delete | Delete a user | write | | users_enable | Enable a disabled user | write | | users_disable | Disable a user | write | | users_revoke_subscription | Revoke subscription (regenerate link) | write | | users_reset_traffic | Reset traffic counter | write |

Nodes (11 tools)

| Tool | Description | Mode | |------|-------------|------| | nodes_list | List all nodes | read | | nodes_get | Get node by UUID | read | | nodes_create | Create a new node | write | | nodes_update | Update node settings | write | | nodes_delete | Delete a node | write | | nodes_enable | Enable a node | write | | nodes_disable | Disable a node | write | | nodes_restart | Restart a specific node | write | | nodes_restart_all | Restart all nodes | write | | nodes_reset_traffic | Reset node traffic counter | write | | nodes_reorder | Reorder nodes | write |

Hosts (5 tools)

| Tool | Description | Mode | |------|-------------|------| | hosts_list | List all hosts | read | | hosts_get | Get host by UUID | read | | hosts_create | Create a new host | write | | hosts_update | Update host settings | write | | hosts_delete | Delete a host | write |

System (8 tools)

| Tool | Description | Mode | |------|-------------|------| | system_stats | Panel statistics (users, nodes, traffic, CPU, memory) | read | | system_bandwidth_stats | Bandwidth statistics | read | | system_nodes_metrics | Node metrics | read | | system_nodes_statistics | Node statistics | read | | system_health | Panel health check | read | | system_metadata | Panel version and metadata | read | | system_generate_x25519 | Generate X25519 key pair | read | | auth_status | Check authentication status | read |

Subscriptions (5 tools)

| Tool | Description | Mode | |------|-------------|------| | subscriptions_list | List all subscriptions | read | | subscriptions_get_by_uuid | Get subscription by UUID | read | | subscriptions_get_by_username | Get subscription by username | read | | subscriptions_get_by_short_uuid | Get subscription by short UUID | read | | subscription_info | Get subscription info | read |

Config Profiles & Inbounds (2 tools)

| Tool | Description | Mode | |------|-------------|------| | config_profiles_list | List config profiles | read | | inbounds_list | List all inbounds | read |

Internal Squads (6 tools)

| Tool | Description | Mode | |------|-------------|------| | squads_list | List all squads | read | | squads_create | Create a squad | write | | squads_update | Update a squad | write | | squads_delete | Delete a squad | write | | squads_add_users | Add users to a squad | write | | squads_remove_users | Remove users from a squad | write |

HWID Devices (3 tools)

| Tool | Description | Mode | |------|-------------|------| | hwid_devices_list | List user's HWID devices | read | | hwid_device_delete | Delete a specific device | write | | hwid_devices_delete_all | Delete all user's devices | write |

Resources

| URI | Description | |-----|-------------| | remnawave://stats | Current panel statistics | | remnawave://nodes | All nodes status | | remnawave://health | Panel health status | | remnawave://users/{uuid} | Specific user details |

Prompts

| Prompt | Description | |--------|-------------| | create_user_wizard | Step-by-step user creation guide | | node_diagnostics | Node troubleshooting | | traffic_report | Traffic usage report | | user_audit | Complete user audit | | bulk_user_cleanup | Find and manage expired users |

Example Queries

"Show me all users with expired subscriptions"
"Create user vasya with 50 GB limit for one month"
"Restart node amsterdam-01"
"Give me a traffic report for the last week"
"Disable users who exceeded their traffic limit"
"Which nodes are offline right now?"

Project Structure

src/
├── index.ts              # Entry point (stdio transport)
├── server.ts             # McpServer setup
├── config.ts             # Environment config
├── client/
│   └── index.ts          # Remnawave HTTP client
├── tools/
│   ├── helpers.ts        # Result formatting helpers
│   ├── index.ts          # Tool registration
│   ├── users.ts          # User management
│   ├── nodes.ts          # Node management
│   ├── hosts.ts          # Host management
│   ├── system.ts         # System & auth
│   ├── subscriptions.ts  # Subscriptions
│   ├── inbounds.ts       # Config profiles & inbounds
│   ├── squads.ts         # Internal squads
│   └── hwid.ts           # HWID devices
├── resources/
│   └── index.ts          # MCP resources
└── prompts/
    └── index.ts          # MCP prompts

License

MIT

MCP-сервер для Remnawave Panel

MCP-сервер (Model Context Protocol), предоставляющий LLM-клиентам (Claude Desktop, Cursor, Windsurf и др.) инструменты для управления VPN-панелью Remnawave.

Возможности

51 инструмент — полное управление пользователями, нодами, хостами, подписками, группами, HWID-устройствами и системой
3 ресурса — статистика панели, статус нод, проверка здоровья в реальном времени
5 промптов — пошаговые сценарии для типичных задач
Readonly-режим — ограничение только чтением для безопасного мониторинга
Поддержка Caddy — заголовок X-Api-Key для панелей за Caddy с кастомным путём
Type-safe — построен на @remnawave/backend-contract для валидации API-маршрутов
stdio транспорт — работает с Claude Desktop, Cursor, Windsurf и любым MCP-совместимым клиентом

Требования

Node.js >= 22
Remnawave панель с API-токеном (Настройки > API Tokens)

Установка

git clone https://github.com/TrackLine/mcp-remnawave.git
cd mcp-remnawave 
npm install
npm run build

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

Создайте файл .env или передайте переменные окружения:

| Переменная | Обязательная | Описание | |------------|-------------|----------| | REMNAWAVE_BASE_URL | Да | URL панели (например https://vpn.example.com) | | REMNAWAVE_API_TOKEN | Да | API-токен из настроек панели | | REMNAWAVE_API_KEY | Нет | API-ключ для аутентификации через Caddy reverse proxy | | REMNAWAVE_READONLY | Нет | true для включения режима только чтения |

REMNAWAVE_BASE_URL=https://vpn.example.com
REMNAWAVE_API_TOKEN=ваш-api-токен

Caddy с кастомным путём

Если ваша панель Remnawave развёрнута за Caddy с кастомным путём и защитой API-ключом, укажите полный путь в base URL и предоставьте API-ключ:

REMNAWAVE_BASE_URL=https://example.com/your-secret-path/api
REMNAWAVE_API_KEY=ваш-caddy-api-ключ

Заголовок X-Api-Key будет автоматически добавляться к каждому запросу.

Режим Readonly

Установите REMNAWAVE_READONLY=true, чтобы отключить все операции записи (создание, обновление, удаление, включение, отключение, перезапуск, отзыв, сброс). Будут зарегистрированы только инструменты чтения.

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

В readonly-режиме количество доступных инструментов сокращается с 51 до 21:

| Категория | Доступные инструменты | |-----------|----------------------| | Пользователи | users_list, users_get, users_get_by_username, users_get_by_short_uuid | | Ноды | nodes_list, nodes_get | | Хосты | hosts_list, hosts_get | | Система | все 8 инструментов (только чтение по своей природе) | | Подписки | все 5 инструментов (только чтение по своей природе) | | Конфиг-профили | все 2 инструмента (только чтение по своей природе) | | Группы | squads_list | | HWID | hwid_devices_list |

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

Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

{
  "mcpServers": {
    "remnawave": {
      "command": "node",
      "args": ["/абсолютный/путь/к/remnawave-mcp/dist/index.js"],
      "env": {
        "REMNAWAVE_BASE_URL": "https://vpn.example.com",
        "REMNAWAVE_API_TOKEN": "ваш-api-токен",
        "REMNAWAVE_API_KEY": "ваш-caddy-api-ключ",
        "REMNAWAVE_READONLY": "false"
      }
    }
  }
}

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

Добавьте в .cursor/mcp.json или .windsurf/mcp.json вашего проекта:

{
  "mcpServers": {
    "remnawave": {
      "command": "node",
      "args": ["/абсолютный/путь/к/remnawave-mcp/dist/index.js"],
      "env": {
        "REMNAWAVE_BASE_URL": "https://vpn.example.com",
        "REMNAWAVE_API_TOKEN": "ваш-api-токен",
        "REMNAWAVE_API_KEY": "ваш-caddy-api-ключ",
        "REMNAWAVE_READONLY": "false"
      }
    }
  }
}

Docker

npm run build
docker compose up -d

Переменные окружения передаются через .env файл или docker-compose.yml.

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

Пользователи (11 инструментов)

| Инструмент | Описание | Режим | |------------|----------|-------| | users_list | Список пользователей с пагинацией | read | | users_get | Получить пользователя по UUID | read | | users_get_by_username | Получить пользователя по username | read | | users_get_by_short_uuid | Получить пользователя по short UUID | read | | users_create | Создать нового пользователя | write | | users_update | Обновить настройки пользователя | write | | users_delete | Удалить пользователя | write | | users_enable | Включить пользователя | write | | users_disable | Отключить пользователя | write | | users_revoke_subscription | Отозвать подписку (перегенерировать ссылку) | write | | users_reset_traffic | Сбросить счётчик трафика | write |

Ноды (11 инструментов)

| Инструмент | Описание | Режим | |------------|----------|-------| | nodes_list | Список всех нод | read | | nodes_get | Получить ноду по UUID | read | | nodes_create | Создать новую ноду | write | | nodes_update | Обновить настройки ноды | write | | nodes_delete | Удалить ноду | write | | nodes_enable | Включить ноду | write | | nodes_disable | Отключить ноду | write | | nodes_restart | Перезапустить ноду | write | | nodes_restart_all | Перезапустить все ноды | write | | nodes_reset_traffic | Сбросить трафик ноды | write | | nodes_reorder | Переупорядочить ноды | write |

Хосты (5 инструментов)

| Инструмент | Описание | Режим | |------------|----------|-------| | hosts_list | Список всех хостов | read | | hosts_get | Получить хост по UUID | read | | hosts_create | Создать новый хост | write | | hosts_update | Обновить настройки хоста | write | | hosts_delete | Удалить хост | write |

Система (8 инструментов)

| Инструмент | Описание | Режим | |------------|----------|-------| | system_stats | Статистика панели (пользователи, ноды, трафик, CPU, память) | read | | system_bandwidth_stats | Статистика пропускной способности | read | | system_nodes_metrics | Метрики нод | read | | system_nodes_statistics | Статистика нод | read | | system_health | Проверка здоровья панели | read | | system_metadata | Версия и метаданные панели | read | | system_generate_x25519 | Генерация пары ключей X25519 | read | | auth_status | Проверка статуса аутентификации | read |

Подписки (5 инструментов)

| Инструмент | Описание | Режим | |------------|----------|-------| | subscriptions_list | Список всех подписок | read | | subscriptions_get_by_uuid | Подписка по UUID | read | | subscriptions_get_by_username | Подписка по username | read | | subscriptions_get_by_short_uuid | Подписка по short UUID | read | | subscription_info | Информация о подписке | read |

Конфиг-профили и Inbounds (2 инструмента)

| Инструмент | Описание | Режим | |------------|----------|-------| | config_profiles_list | Список конфиг-профилей | read | | inbounds_list | Список всех inbounds | read |

Внутренние группы (6 инструментов)

| Инструмент | Описание | Режим | |------------|----------|-------| | squads_list | Список групп | read | | squads_create | Создать группу | write | | squads_update | Обновить группу | write | | squads_delete | Удалить группу | write | | squads_add_users | Добавить пользователей в группу | write | | squads_remove_users | Убрать пользователей из группы | write |

HWID-устройства (3 инструмента)

| Инструмент | Описание | Режим | |------------|----------|-------| | hwid_devices_list | Список устройств пользователя | read | | hwid_device_delete | Удалить конкретное устройство | write | | hwid_devices_delete_all | Удалить все устройства пользователя | write |

Ресурсы

| URI | Описание | |-----|----------| | remnawave://stats | Текущая статистика панели | | remnawave://nodes | Статус всех нод | | remnawave://health | Состояние здоровья панели | | remnawave://users/{uuid} | Данные конкретного пользователя |

Промпты

| Промпт | Описание | |--------|----------| | create_user_wizard | Пошаговое создание пользователя | | node_diagnostics | Диагностика ноды | | traffic_report | Отчёт по трафику | | user_audit | Полный аудит пользователя | | bulk_user_cleanup | Поиск и управление просроченными пользователями |

Примеры запросов

«Покажи мне всех пользователей с истёкшей подпиской»
«Создай пользователя vasya с лимитом 50 ГБ на месяц»
«Перезапусти ноду amsterdam-01»
«Дай отчёт по трафику за последнюю неделю»
«Отключи пользователей, которые превысили лимит трафика»
«Какие ноды сейчас офлайн?»

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

src/
├── index.ts              # Точка входа (stdio транспорт)
├── server.ts             # Настройка McpServer
├── config.ts             # Конфигурация окружения
├── client/
│   └── index.ts          # HTTP-клиент Remnawave
├── tools/
│   ├── helpers.ts        # Хелперы форматирования
│   ├── index.ts          # Регистрация инструментов
│   ├── users.ts          # Управление пользователями
│   ├── nodes.ts          # Управление нодами
│   ├── hosts.ts          # Управление хостами
│   ├── system.ts         # Система и авторизация
│   ├── subscriptions.ts  # Подписки
│   ├── inbounds.ts       # Конфиг-профили и inbounds
│   ├── squads.ts         # Внутренние группы
│   └── hwid.ts           # HWID-устройства
├── resources/
│   └── index.ts          # MCP-ресурсы
└── prompts/
    └── index.ts          # MCP-промпты

Лицензия

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

mcp-remnawave

MCP Server for Remnawave Panel

Features

Requirements

Installation

Configuration

Caddy with Custom Path

Readonly Mode

Usage with Claude Desktop

Usage with Cursor / Windsurf

Docker

Available Tools

Users (11 tools)

Nodes (11 tools)

Hosts (5 tools)

System (8 tools)

Subscriptions (5 tools)

Config Profiles & Inbounds (2 tools)

Internal Squads (6 tools)

HWID Devices (3 tools)

Resources

Prompts

Example Queries

Project Structure

License

MCP-сервер для Remnawave Panel

Возможности

Требования

Установка

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

Caddy с кастомным путём

Режим Readonly

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

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

Docker

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

Пользователи (11 инструментов)

Ноды (11 инструментов)

Хосты (5 инструментов)

Система (8 инструментов)

Подписки (5 инструментов)

Конфиг-профили и Inbounds (2 инструмента)

Внутренние группы (6 инструментов)

HWID-устройства (3 инструмента)

Ресурсы

Промпты

Примеры запросов

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

Лицензия