A
licenseA
qualityB
maintenanceMCP server for Remnawave panel API. Manage VPN users, nodes, hosts, and system stats from Claude Code or any MCP-compatible client.
34
MIT
mcp-remnawave
by Maaagiic
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-remnawaveShow me the list of active users and their traffic limits."
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
MCP server for the Remnawave VPN panel — tools generated from the panel's own API contract
English · Русский
Lets an MCP client — Claude Code, Claude Desktop, Cursor or any other — read and manage users, nodes, hosts, config profiles, squads, subscriptions, node plugins, traffic statistics, billing and HWID devices through the panel's REST API.
Every tool is built from @remnawave/backend-contract —
the package the panel itself validates requests with. Route, HTTP method and arguments come
from the contract, so a tool cannot drift away from the API: updating for a new panel
version means bumping one dependency.
Maintained fork of TrackLine/mcp-remnawave.
✨ Highlights
📜 Generated from the contract | 203 tools cover the whole API of Remnawave 3.4. A test fails when the contract gains a command that has no tool |
🚦 Three access levels | Read only · read + write · read + write + destructive. Tools above the chosen level are not registered at all |
🧩 Toolsets | Register only the groups you need ( |
🧾 Nothing is dropped silently | An argument the endpoint does not know is an error, not an update that quietly did nothing. Validation errors name the field |
🗂 One install, many panels | Panel config is looked up in the current project first — the active panel is whichever project you are working in |
🪶 Compact answers | List tools leave out xray configs and raw inbound objects unless asked ( |
Related MCP server: remnawave-mcp
🚀 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 call system_metadata — it should answer with the panel version.
{
"mcpServers": {
"remnawave": {
"command": "node",
"args": ["/absolute/path/to/mcp-remnawave/dist/index.js"]
}
}
}The server speaks MCP over stdio, so the client starts one container per session — there is no port to expose and nothing to keep running.
docker build -t remnawave-mcp .
claude mcp add --scope user remnawave -- docker run -i --rm --env-file /absolute/path/to/.env remnawave-mcpAny 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
Variable | Default | Description |
| — (required) | Panel URL, e.g. |
| — (required) | API token (Bearer) — Panel → API tokens |
|
|
|
|
|
|
| all | Comma-separated toolsets to register, e.g. |
| — | Comma-separated tool names to leave out; |
|
| Timeout for one request to the panel |
| — |
|
| — | Explicit path to a config file |
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 fallbackMCP 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. If nothing is found, the server exits with a message
that lists the files it looked at.
Access levels
Every tool has a kind, shown to the client as MCP annotations (readOnlyHint, destructiveHint):
Kind | What it is | Registered when |
read | Does not change the panel (includes POST endpoints that only look things up) | always |
write | Creates or changes something |
|
destructive | Deletes data, or acts on every user or node at once | write mode and |
Tools above the chosen level are not registered, so the client cannot even attempt them;
calling one by name answers with the reason it is off. A sensible setup for daily work is
write mode with REMNAWAVE_ALLOW_DESTRUCTIVE=false.
🧰 Tools
203 contract tools in 12 toolsets, plus api_request.
Toolset | Read | Write | Destructive |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| — |
|
|
| — | — |
|
|
|
|
|
|
|
|
|
| — |
|
Good to know:
Users are identified by a numeric
id, not a uuid. To search by telegramId, email, tag or status useusers_listwithfilters: [{"id": "telegramId", "value": 123456789}].A tool takes exactly the fields of its endpoint. Unknown arguments are rejected before anything is sent; values are forwarded as given, with no defaults added.
config_profiles_updatewithconfigreplaces the whole xray config of the profile — read it, patch it, write it back. Nodes using the profile restart xray to apply it.Compact lists:
nodes_list,config_profiles_list,squads_listandinbounds_listleave out bulky parts by default; passfull: truefor the raw panel response.squads_add_all_users/squads_remove_all_usersact on every user. For selected users usesquads_add_many_users/squads_remove_many_users.connections_*_requeststart a job on the node and return ajobId; fetch the outcome with the matching*_resulttool.api_requestsends a raw request for endpoints the installed contract does not describe yet. GET works in every mode; other methods need write mode with destructive tools allowed.api_tokens_*andsettings_*need an API token with the matching scope — otherwise the panel answersForbidden.
🔁 Panel versions
Tools describe the API of contract 3.4.15 (checked against a live 3.4.4 panel). The server targets Remnawave 3.4; for a 2.x or 3.0–3.3 panel use release v2.1.0.
To follow a new panel release:
npm install --save-exact @remnawave/backend-contract@<version> zod@<the zod version it depends on>
npm run checknpm run check fails with the list of contract commands that have no tool yet (add them to
src/tools/registry.ts) and shows every changed argument as a snapshot diff.
⬆️ Upgrading from 2.x
3.0 is a breaking release: tools now follow the 3.4 API exactly.
Removed:
ip_control_*(the panel moved these routes — useconnections_*),hosts_bulk_set_inbound/hosts_bulk_set_port(usehosts_bulk_update),subscriptions_get_subpage_config.Renamed, because the old names promised something else:
squads_add_users/squads_remove_usersandexternal_squads_add_users/_remove_users→*_add_all_users/*_remove_all_users. The endpoints take no user list and affect every user; selected users go through the newsquads_add_many_users/squads_remove_many_users.Arguments changed wherever 2.x had drifted from the panel: hosts take
tags(array) andinternalSquadsinstead oftagandexcludedInternalSquads;nodes_restarttakesforceRestart;nodes_bulk_*takeuuids;*_reordertake a list of{uuid, viewPosition};*_clonetakecloneFromUuid; HWID tools takeuserId; tools that address one user (users_get,users_delete, …) takeuserIdinstead ofid.New: traffic statistics (
bandwidth_*), geocheck, shared lists, node integrations, subscription settings, tags for profiles/squads/templates,hosts_clone,hosts_reorder,hosts_bulk_update,users_stream,api_request.docker-compose.ymlis gone: the server is a stdio process, see the Docker section above.
🛠 Development
npm run dev # tsup --watch
npm run build # tsup → dist/index.js
npm run check # typecheck + testsThe tests run the real server in-process against a mocked panel: they snapshot the tool
surface (names, schemas, annotations) and the HTTP request of every tool, so any change
to what a tool sends shows up in review. Accept intended changes with
UPDATE_SNAPSHOTS=1 npm test.
Two scripts check a real panel, without changing anything on it:
node scripts/smoke.mjs path/to/.env # calls every read tool, reports routes the panel does not serve
node scripts/stdio-check.mjs path/to/project # starts dist/index.js over stdio like a client wouldThe source is small on purpose: src/tools/registry.ts maps tool names to contract
commands, src/tools/contract.ts turns a command into a tool.
📄 License
MIT. Upstream authorship: TrackLine/mcp-remnawave.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Any REST/SOAP/GraphQL/OData/SQL API as MCP tools for Claude & ChatGPT. 338 connectors: SAP, ERP.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
Remote MCP for RunComfy: ComfyUI deployments, hosted models, LoRA training. 31 tools.
A paid remote MCP for ClawManager, built to return verdicts, receipts, usage logs, and audit-ready J
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to manage a Remnawave panel through its full API, covering users, nodes, hosts, subscriptions, and more with configurable tool profiles and read/write token access.12 npmMIT
- AlicenseCqualityBmaintenanceEnables managing a Remnawave VPN panel from MCP clients, providing tools for users, nodes, subscriptions, statistics, billing, and system operations, plus resources and prompts for common admin tasks.1907 npmMIT
- AlicenseCqualityCmaintenanceEnables AI clients to drive the full Remnawave panel API, exposing one tool per method+path operation (users, nodes, hosts, subscriptions, inbound, bulk actions) plus search, describe, status, audit and metrics helpers. Read-only/read-write gating, deny rules, confirm-preview and dry-run, response secret redaction and an audit journal keep mutations controlled.2227 npmMIT