Remnawave Tools MCP

Flat, safety-gated stdio MCP wrapper for remnawave-mcp@0.2.1.

The upstream Remnawave MCP exposes a generic remnawave_api tool. This wrapper keeps that upstream behavior but exposes one MCP tool per Remnawave domain operation.

Examples:

• remnawave_system_get_health
• remnawave_nodes_list
• remnawave_nodes_get
• remnawave_nodes_update
• remnawave_users_get
• remnawave_users_update
• remnawave_internal_squads_add_users
• remnawave_external_squads_add_users
• remnawave_subscription_settings_get

Meta tools:

• remnawave_discover
• remnawave_describe

Tool Map

The wrapper preserves every low-level Remnawave operation discovered from remnawave-mcp@0.2.1. The current catalog has 152 low-level tools plus meta and operator helpers.

Domain	Examples	Safety
system	health, metadata, stats, node metrics	read, mutation for key generation
nodes	list/get/create/update/disable/enable/restart/reset traffic	read + gated mutation
users	list/get/lookup/create/update/disable/enable/delete/bulk actions	sensitive read + gated mutation
internal_squads	list/get/create/update/add users/remove users	read + gated mutation
external_squads	list/get/create/update/add users/remove users	read + gated mutation
hosts, profiles, templates, snippets	config object management	read + gated mutation
subscriptions, public_subscriptions	subscription lookups and raw/subpage reads	sensitive read
hwid, infra_billing, bandwidth_stats	devices, billing metadata, usage stats	read/sensitive read + gated mutation

Priority operations for nodes, users, internal_squads, and external_squads expose typed top-level fields in addition to the generic payload escape hatch. Callers can pass fields like uuid, username, address, userUuids, activeInternalSquads, or activeExternalSquads directly.

Operator Tools

These convenience tools sit on top of the low-level operations:

• remnawave_node_get_config
• remnawave_node_update_config
• remnawave_squad_add_users
• remnawave_user_suspend
• remnawave_user_set_squads

They forward to the same upstream remnawave_api calls and use the same safety rules. The low-level tools remain available for complete API coverage.

Safety

Credentials are read only from environment variables:

• REMNAWAVE_BASE_URL
• REMNAWAVE_API_TOKEN
• REMNAWAVE_VERSION

Mutating operations are locally blocked unless both are true:

• REMNAWAVE_TOOLS_ALLOW_MUTATIONS=true
• the MCP call sets mutationApproved=true

By default, mutating calls return LOCAL_MUTATION_BLOCKED and are not forwarded upstream.

Hard-to-reverse operations such as deletes, bulk mutations, and restart_all also require an operation-specific confirmation phrase:

{ "confirmPhrase": "confirm users.delete" }

Sensitive read results are redacted before returning through this wrapper for user, subscription, connection-key, short-UUID, and device-oriented operations.

Examples

Read a node:

{
  "tool": "remnawave_nodes_get",
  "arguments": { "uuid": "node-uuid" }
}

Update a node, assuming local mutation execution is enabled:

{
  "tool": "remnawave_node_update_config",
  "arguments": {
    "uuid": "node-uuid",
    "name": "edge-a",
    "address": "203.0.113.10",
    "mutationApproved": true
  }
}

Add users to an external squad:

{
  "tool": "remnawave_squad_add_users",
  "arguments": {
    "squadType": "external",
    "squadUuid": "squad-uuid",
    "userUuids": ["user-uuid"],
    "mutationApproved": true
  }
}

Advanced callers can still use the generic escape hatch:

{
  "tool": "remnawave_users_update",
  "arguments": {
    "uuid": "user-uuid",
    "data": { "description": "managed by automation" },
    "payload": { "tag": "ops" },
    "mutationApproved": true
  }
}

Install

npm ci --include=dev
npm run build

Then point your MCP runtime at:

node /path/to/remnawave-tools-mcp/dist/index.js

Example environment:

REMNAWAVE_BASE_URL=https://remnawave.example.com
REMNAWAVE_API_TOKEN=your-token
REMNAWAVE_VERSION=2.7.4
REMNAWAVE_TOOLS_ALLOW_MUTATIONS=false

Development

npm ci --include=dev
npm test
npm run build

Unit tests use a fake upstream MCP server and do not require a real Remnawave token.

Notes

• The operation catalog targets Remnawave 2.7.0 through 2.7.4 and fails closed if upstream discovery does not match.
• responseMode=raw is only allowed for safe system reads.
• This wrapper intentionally shells out to remnawave-mcp@0.2.1 instead of reimplementing the Remnawave HTTP API.