Remnawave MCP Server

Local setup required. This server has to be cloned and prepared on your machine before you register it in Claude Code.
1

Set the server up locally

Run this once to clone and prepare the server before adding it to Claude Code.

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

Register it in Claude Code

After the local setup is done, run this command to point Claude Code at the built server.

Run in terminal
claude mcp add -e "REMNAWAVE_BASE_URL=${REMNAWAVE_BASE_URL}" -e "REMNAWAVE_API_TOKEN=${REMNAWAVE_API_TOKEN}" remnawave-mcp -- node "<FULL_PATH_TO_MCP_REMNAWAVE>/dist/index.js"

Replace <FULL_PATH_TO_MCP_REMNAWAVE>/dist/index.js with the actual folder you prepared in step 1.

Required:REMNAWAVE_BASE_URLREMNAWAVE_API_TOKEN+ 2 optional
README.md

Manage Remnawave VPN panels with 51 specialized tools for administration.

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 Creat

Tools (5)

users_listList all users with pagination
users_getGet user by UUID
users_createCreate a new user
nodes_listList all nodes
nodes_getGet node by UUID

Environment Variables

REMNAWAVE_BASE_URLrequiredPanel URL (e.g. https://vpn.example.com)
REMNAWAVE_API_TOKENrequiredAPI token from panel settings
REMNAWAVE_API_KEYAPI key for Caddy reverse proxy authentication
REMNAWAVE_READONLYSet to true to enable readonly mode

Configuration

claude_desktop_config.json
{"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"}}}}

Try it

→List all active users on the VPN panel.
→Get the current status and health of all nodes.
→Create a new user account with the provided details.
→Reset the traffic counter for the user with the specified UUID.
→Check the current subscription status for my VPN account.

Frequently Asked Questions

What are the key features of Remnawave MCP?

51 specialized tools for managing users, nodes, hosts, and subscriptions. Real-time panel statistics and node health monitoring. Readonly mode for safe monitoring and auditing. Type-safe API interaction using backend-contract validation. Support for Caddy reverse proxy with custom path authentication.

What can I use Remnawave MCP for?

Automating user onboarding and subscription management for VPN services. Monitoring VPN node health and system performance in real-time. Performing bulk administrative tasks like traffic resets via natural language. Auditing VPN panel activity using the restricted read-only mode.

How do I install Remnawave MCP?

Install Remnawave MCP by running: git clone https://github.com/TrackLine/mcp-remnawave.git && cd mcp-remnawave && npm install && npm run build

What MCP clients work with Remnawave MCP?

Remnawave MCP works with any MCP-compatible client including Claude Desktop, Claude Code, Cursor, and other editors with MCP support.

Turn this server into reusable context

Keep Remnawave MCP docs, env vars, and workflow notes in Conare so your agent carries them across sessions.

Need the old visual installer? Open Conare IDE.
Open Conare
View all cloud servers →

Related MCP Servers

Kilntainers
Give Every Agent an Ephemeral Linux Sandbox — via MCP
cloud36 stars
Dynamics 365 Finance & Operations
Production-ready MCP server for Microsoft Dynamics 365 Finance & Operations
cloud25 stars
Fleet
Docker production management CLI + MCP server
cloud14 stars
App Store Connect MCP
A Model Context Protocol server for the App Store Connect API.
cloud9 stars
RootCause
AI-native SRE for Kubernetes incidents.
cloud8 stars
Google Workspace Code MCP
A code-first MCP server to execute JS/TS with Google Workspace API access.
cloud8 stars