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.

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.

Related MCP server: safe-oas2mcp

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.