mcp-remnawave

MCP-Server für das Remnawave VPN-Panel — aktualisiert für Remnawave 3.x

English · Русский

Ermöglicht es einem MCP-Client — Claude Code, Claude Desktop, Cursor oder sonst einem — Benutzer, Nodes, Hosts, Konfigurationsprofile, Squads, Subscription-Vorlagen, Abrechnung und HWID-Geräte über die REST-API des Panels zu lesen und zu verwalten.

Gepflegter Fork von TrackLine/mcp-remnawave v1.2.0, an Remnawave 3.x angeglichen (gegen ein Live-3.3.x-Panel verifiziert) und so umgebaut, dass Tool-Schemas nicht mehr von der Panel-API abweichen können.

✨ Highlights

Related MCP server: remnawave-mcp-server

🚀 Schnellstart

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"

Das war's. Bitte deinen Client um system_metadata — er sollte mit der Panel-Version antworten.

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

Jeder stdio-MCP-Client funktioniert — zeig ihn auf node dist/index.js und übergib die Umgebungsvariablen aus der Tabelle unten (oder verlass dich auf die Konfigurationsdateisuche).

⚙️ Konfiguration

Woher die Konfiguration stammt

Der Server hält bei der ersten Datei an, die REMNAWAVE_BASE_URL und REMNAWAVE_API_TOKEN liefert:

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 starten Stdio-Server mit cwd im Projektroot, sodass bei einer einzigen globalen Installation ** das aktive Panel das Projekt ist, in dem du gerade arbeitest**. Um ein Panel hinzuzufügen, legst du einfach eine .remnawave.env ins Projekt — am Server muss nichts geändert werden. Bereits in der Umgebung vorhandene Variablen werden niemals überschrieben, also gewinnt immer die von der Client-Registrierung übergebene Umgebung.

Readonly-Modus

Starte mit REMNAWAVE_READONLY=true. Schreib-Tools (create / update / delete / enable / disable / bulk) werden in diesem Modus überhaupt nicht eingetragen, sodass der Client es nicht einmal versuchen kann. Setze es auf false und starte den Server neu, sobald du wirklich schreiben musst.

🧰 Tools

Woelle 150 Tools, passend zur Panel-API gruppiert. Lese-Tools gibt es immer; Schreib-Tools nur, wenn der Readonly-Modus aus ist.

• Suche per telegramId / E-Mail / Tag / Status: users_list mit filters: [{"id": "telegramId", "value": 123456789}] (+ optional filterModes, sorting). Das ersetzt die in 3.x entfernten by-*-Routen.

• users_resolve nimmt genau eine der Angaben id, shortUuid, username.

• Bulk-Tools nehmen userIds: number[] (1–500); users_bulk_update verschachtelt geänderte Felder unter fields.

• users_create akzeptiert explizit vlessUuid / ssPassword / trojanPassword / shortUuid — gut für Dienstkonten.

• config_profiles_update mit config ersetzt die gesamte Xray-Konfiguration des Profils — lesen, patchen, zurückschreiben.

• hosts_create erfordert inbound: { configProfileUuid, configProfileInboundUuid }.

api_tokens_list und settings_* benötigen einen API-Token mit den passenden Berechtigungen — andernfalls antwortet das Panel mit Forbidden.

🔧 Änderungen gegenüber dem Upstream

• Numerische Benutzer-IDs überall; users_get_by_telegram_id / _by_email / _by_tag / _by_subscription_uuid und subscriptions_get_by_uuid entfernt (die Routen existieren nicht mehr).

• contractTool() — Schreib-Tools registrieren sich mit RequestSchema.shape aus dem Vertrag. Vorher: 20 von 23 Schreib-Tools machten eine Teilmenge der Felder verfügbar, und das MCP SDK verwarf den Rest stillschweigend.

• users_* bleiben handgeschrieben; der installierte Vertrag deklariert für Benutzer weiterhin uuid.

• Neu: users_extend_expiration, users_accessible_nodes, subscriptions_get_by_user_id, subscription_templates_list / get / update; config_profiles_update akzeptiert config.

• Client: vollständige API-Fehler-Bodies, leere 2xx-Bodies bei Bulk-Operationen behandelt, handgebaute, trailing-slash-sichere Pfade für Routen, die es nur in 3.x gibt.

• Enums aus dem Vertrag (RESET_PERIODS inkl. MONTH_ROLLING, USERS_STATUS).

• Multi-Panel-Konfigurationssuche; read-only standardmäßig empfohlen; Version angehoben auf 2.0.0.

🛠 Entwicklung

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

🐳 Docker

docker compose up -d

Siehe docker-compose.yml und übergebe dieselben Umgebungsvariablen.

📄 Lizenz

MIT. Urheberschaft des Upstreams: TrackLine/mcp-remnawave.