mcp-remnawave

Servidor MCP para el panel VPN Remnawave — actualizado para Remnawave 3.x

English· Русский

Permite que un cliente MCP — Claude Code, Claude Desktop, Cursor o cualquier otro — lee y administre usuarios, nodos, hosts, perfiles de configuracón, esquadrones, plantilas de suscripción, facturación y disposivos HWID a través de la API REST del panel.

Fork con mantenimento activo de TrackLine/mcp-remnawave v1.2.0, pue lo al día con Remnawave 3.x (verificado contra un panel real en 3.3.x) y reestruct urdo para que los esquemas de las herramientas ya no puedan desviarse de la API del panel.

✨ Características

Related MCP server: remnawave-mcp-server

Inicio rápido

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"

Eso es todo. Pídele a tu client que ejecute system_metadata — debería respondetre con la versión del panel.

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

Cualquier cliente MCP con stdio funciona: indícale que ejecute node dist/index.js y pásale las variables de entrono de la tabla siguiente (o confía en la búsueda del archivo de configurac).

️ Configuración

De dónde viene la configuación

El servidor se detiene en el primer archivo que proporcione REMNAWAVE_BASE_URL y 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

Los clientes MCP inician los servidores stdio con cwd fijado en laraíz del proyecto, de modo que con una única instalación globál el panel activo es el del proyecto en el que estés trabajando. Para añadir te un panel, coloca un .remnawave.env en su proyecto — no hay que cambar nada en el lado del servidor. Las variables ya presentes en el entorno never se sobrescriben, así que las que envía el registro del cliente siempre tienen la priorida.

Modo solo lecturas

Empieza con REMNAWAVE_READ_ONLY=true. Las herramientas de **(imple/update /delete/enable/disable/bulk) **no se registran en absoluto** en este modo, así que el cliente ni siquiera puede intenarlas. Cámbiala a false` y reinicia el servidor cuando de verdad necesites escritir.

💰 Herramients

Unas 150 herramients, agrupadas como la API del panel. Always available read tools; waiting for disable.

• Búsueda por telegramId / correo / etiqueta / estado: users_list con filters: [{"id": "telegramId", "value": 123456789}] (opcional += filterModes, sorting). Esto reflaza las rutas obsoletas by-* que se eliminaron en 3.x.

• users_resolve solo un de estos valores: id, shortUuid, username.

• Las herramients masivas reciben userIds: number[] (1–500); users_bulk_update anida los campos cambiados en fields.

• users_create acepta vlessUuid / ssPassword / trojanPassword / shortUuid explícitos — práctico para cuentas de servicio.

• config_profiles_update con config reemplaza toda la configuación xray del perfil — léalo, modifícalo y escríbelo de nuevo.

• hosts_create requiere inbound: {configProfileUuid, configProfileInboundUuid}.

| Grupo | Lectura | Escritra | |-------------------------- |------------------------------------ | | Squads | squads_list, squads_accessible_nodes, external_squads_list / get | squads_create / update / delete, squads_add_users, squads_remove_users, external_squads_* | | Suscripciones | subscriptions_list, subscriptions_get_by_username, subscriptions_get_by_short_uuid, subscriptions_get_by_user_id, subscriptions_get_raw_by_short_uuid, subscriptions_get_connection_keys, subscription_info | — | | Plantillas & páginas | subscription_templates_list / get, sub_page_configs_list / get | subscription_templates_update, sub_page_configs_* |

| Grupo | Lectura | Escritura | |------------------ |------------------------------------ | | HWID | hwid_devices_list, hwid_devices_list_all, hwid_stats, hwid_top_users | hwid_device_create / delete, hwid_devices_delete_all | | Sistema | system_health, system_metadata, system_stats, system_stats_recap, system_bandwidth_stats, system_nodes_metrics, system_nodes_statistics, system_generate_x25519, keygen_get, system_srr_matcher | settings_update | | Facturación | billing_providers_list / get, billing_nodes_list, billing_history_list | billing_provider_*, billing_node_*, billing_history_* | | Plugins de nodo | node_plugins_list / get, node_plugins_torrent_* | node_plugins_* | | Varios | api_tokens_list, snippets_list, metadata_*_get, ip_control_* | api_tokens_*, snippets_*, metadata_*_upsert |

api_tokens_list y settings_* necesitan un token de API con los permisos correspondientes — de lo contrario, el panel responde Forbidden.

🔧 Qué cambió respecto a upstream

• IDs de usuario numéricos en todas partes; se eliminaron users_get_by_telegram_id / _by_email / _by_tag / _by_subscription_uuid y subscriptions_get_by_uuid (las rutas ya no existen).

• contractTool() — las herramientas de escritura se registran con RequestSchema.shape del contrato. Antes: 20 de 23 herramientas de escritura exponían un subconjunto de campos y el MCP SDK descartaba el resto en silencio.

• users_* siguen escritas a mano: el contrato instalado todavía declara uuid para los usuarios.

• Nuevo: users_extend_expiration, users_accessible_nodes, subscriptions_get_by_user_id, subscription_templates_list / get / update; config_profiles_update acepta config.

• Cliente: cuerpos de error completos de la API, cuerpos 2xx vacíos en operaciones masivas gestionados, rutas construidas a mano seguras ante la barra final para rutas exclusivas de la 3.x.

• Enums del contrato (RESET_PERIODS incl. MONTH_ROLLING, USERS_STATUS).

• Búsqueda de configuración en varios paneles; readonly recomendado por defecto; versión actualizada a 2.0.0.

🛠 Desarrollo

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

🐳 Docker

docker compose up -d

Consulta docker-compose.yml y pasa las mismas variables de entorno.

📄 Licencia

MIT. Autoría original: TrackLine/mcp-remnawave.