mcp-remnawave

MCP server for the Remnawave VPN panel — updated for Remnawave 3.x

English · Русский

Lets an MCP client — Claude Code, Claude Desktop, Cursor or any other — read and manage users, nodes, hosts, config profiles, squads, subscription templates, billing and HWID devices through the panel's REST API.

Maintained fork of TrackLine/mcp-remnawave v1.2.0, brought in line with Remnawave 3.x (verified against a live 3.3.x panel) and reworked so that tool schemas can no longer drift away from the panel API.

✨ Highlights

Related MCP server: remnawave-mcp-server

🚀 Quick start

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

cp .env.example .env          # set REMNAWAVE_BASE_URL and REMNAWAVE_API_TOKEN

# Claude Code — available in every project:
claude mcp add --scope user remnawave -- node "$PWD/dist/index.js"

That's it. Ask your client to system_metadata — it should answer with the panel version.

{
  "mcpServers": {
    "remnawave": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-remnawave/dist/index.js"]
    }
  }
}

Any stdio MCP client works — point it at node dist/index.js and pass the environment variables from the table below (or rely on the config file lookup).

⚙️ Configuration

Where the config comes from

The server stops at the first file that provides REMNAWAVE_BASE_URL and REMNAWAVE_API_TOKEN:

1. $REMNAWAVE_ENV_FILE          explicit path
2. <cwd>/.remnawave.env         per-project — add it to .gitignore
3. <cwd>/.env
4. <package>/.env               fallback

MCP clients launch stdio servers with cwd set to the project root, so with a single global install the active panel is whichever project you are working in. To add a panel, drop a .remnawave.env into its project — nothing to change on the server side. Variables already present in the environment are never overridden, so env passed by the client registration always wins.

Readonly mode

Start with REMNAWAVE_READONLY=true. Write tools (create / update / delete / enable / disable / bulk) are not registered at all in this mode, so the client cannot even attempt them. Set it to false and restart the server when you actually need to write.

🧰 Tools

About 150 tools, grouped like the panel API. Read tools are always available; write tools only when readonly is off.

• Search by telegramId / email / tag / status: users_list with filters: [{"id": "telegramId", "value": 123456789}] (+ optional filterModes, sorting). This replaces the by-* routes removed in 3.x.

• users_resolve takes exactly one of id, shortUuid, username.

• Bulk tools take userIds: number[] (1–500); users_bulk_update nests changed fields under fields.

• users_create accepts explicit vlessUuid / ssPassword / trojanPassword / shortUuid — handy for service accounts.

• config_profiles_update with config replaces the whole xray config of the profile — read, patch, write back.

• hosts_create requires inbound: { configProfileUuid, configProfileInboundUuid }.

api_tokens_list and settings_* need an API token with the matching rights — otherwise the panel answers Forbidden.

🔧 What changed vs. upstream

• Numeric user ids everywhere; users_get_by_telegram_id / _by_email / _by_tag / _by_subscription_uuid and subscriptions_get_by_uuid removed (the routes no longer exist).

• contractTool() — write tools register with RequestSchema.shape from the contract. Before: 20 of 23 write tools exposed a subset of fields and the MCP SDK dropped the rest silently.

• users_* remain hand-written: the installed contract still declares uuid for users.

• New: users_extend_expiration, users_accessible_nodes, subscriptions_get_by_user_id, subscription_templates_list / get / update; config_profiles_update takes config.

• Client: full API error bodies, empty 2xx bodies on bulk operations handled, trailing-slash-safe hand-built paths for 3.x-only routes.

• Enums from the contract (RESET_PERIODS incl. MONTH_ROLLING, USERS_STATUS).

• Multi-panel config lookup; readonly recommended by default; version bumped to 2.0.0.

🛠 Development

npm run dev       # tsup --watch
npm run build     # tsup → dist/index.js
npx tsc --noEmit  # typecheck

🐳 Docker

docker compose up -d

See docker-compose.yml and pass the same environment variables.

📄 License

MIT. Upstream authorship: TrackLine/mcp-remnawave.