mcp-remnawave

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
• 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:

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

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"
      }
    }
  }
}

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"
      }
    }
  }
}

Docker

npm run build
docker compose up -d

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

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

"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 промптов — пошаговые сценарии для типичных задач
• 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=https://vpn.example.com
REMNAWAVE_API_TOKEN=ваш-api-токен

Использование с 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-токен"
      }
    }
  }
}

Использование с 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-токен"
      }
    }
  }
}

Docker

npm run build
docker compose up -d

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

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

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

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

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

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

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

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

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

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

Ресурсы

Промпты

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

«Покажи мне всех пользователей с истёкшей подпиской»
«Создай пользователя 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