How do I use remnawave-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@remnawave-mcp Show me the current system stats and node health" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

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 инструмента)

Ресурсы

Промпты

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

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

Лицензия

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API