Skip to content
Back to search

mcp-remnawave

MCP Server for Remnawave Panel

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/trackline--mcp-remnawave/badge.svg)](/listings/trackline--mcp-remnawave)

HTML

<a href="/listings/trackline--mcp-remnawave"><img src="/api/listings/trackline--mcp-remnawave/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/TrackLine/mcp-remnawave.git
cd mcp-remnawave
npm install
npm run build

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 924 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. > [!IMPORTANT]
  2. > PROJECT IS CLOSED, USE PLEASE https://github.com/3APA3A-3AHO3A/remnawave-mcp
  3. # mcp-remnawave
  4. [English](#english) | [Русский](#русский)
  5. ---
  6. <a id="english"></a>
  7. ## MCP Server for Remnawave Panel
  8. MCP server ([Model Context Protocol](https://modelcontextprotocol.io)) providing LLM clients (Claude Desktop, Cursor, Windsurf, etc.) with tools to manage a [Remnawave](https://github.com/remnawave/) VPN panel.
  9. **Version:** 1.2.0 | **Remnawave API:** 2.7.4
  10. ### Features
  11. - **153 tools** — full management of users, nodes, hosts, subscriptions, squads, HWID, config profiles, inbounds, API tokens, billing, snippets, external squads, settings, subscription page configs, node plugins, IP control, and metadata
  12. - **3 resources** — real-time panel stats, node status, health checks
  13. - **5 prompts** — guided workflows for common tasks
  14. - **Readonly mode** — restrict to 69 read-only tools for safe monitoring
  15. - **Caddy support** — `X-Api-Key` header for panels behind Caddy with custom path
  16. - **Type-safe** — built on [@remnawave/backend-contract](https://www.npmjs.com/package/@remnawave/backend-contract) for API route validation
  17. - **stdio transport** — works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client
  18. ### Requirements
  19. - Node.js >= 22
  20. - Remnawave panel with API token (Settings > API Tokens)
  21. ### Installation
  22. ```bash
  23. git clone https://github.com/TrackLine/mcp-remnawave.git
  24. cd mcp-remnawave
  25. npm install
  26. npm run build
  27. ```
  28. ### Configuration
  29. Create a `.env` file or pass environment variables:
  30. | Variable | Required | Description |
  31. |----------|----------|-------------|
  32. | `REMNAWAVE_BASE_URL` | Yes | Panel URL (e.g. `https://vpn.example.com`) |
  33. | `REMNAWAVE_API_TOKEN` | Yes | API token from panel settings |
  34. | `REMNAWAVE_API_KEY` | No | API key for Caddy reverse proxy authentication |
  35. | `REMNAWAVE_READONLY` | No | Set to `true` to enable readonly mode |
  36. ```env
  37. REMNAWAVE_BASE_URL=https://vpn.example.com
  38. REMNAWAVE_API_TOKEN=your-api-token-here
  39. ```
  40. ### Caddy with Custom Path
  41. If your Remnawave panel is deployed behind [Caddy with a custom path and API key protection](https://docs.remnawave.com/docs/security/caddy-with-custom-path/), set the base URL to include the custom path and provide the API key:
  42. ```env
  43. REMNAWAVE_BASE_URL=https://example.com/your-secret-path/api
  44. REMNAWAVE_API_KEY=your-caddy-api-key
  45. ```
  46. The `X-Api-Key` header will be added to every request automatically.
  47. ### Readonly Mode
  48. Set `REMNAWAVE_READONLY=true` to disable all write operations (create, update, delete, enable, disable, restart, revoke, reset). Only read/list tools will be registered.
  49. Useful for monitoring dashboards or shared environments where you want to prevent accidental changes.
  50. In readonly mode, the available tools are reduced from 153 to 69:
  51. | Category | Available tools |
  52. |----------|----------------|
  53. | Users (10) | `users_list`, `users_get`, `users_get_by_username`, `users_get_by_short_uuid`, `users_get_by_telegram_id`, `users_get_by_email`, `users_get_by_tag`, `users_get_by_subscription_uuid`, `users_tags_list`, `users_resolve` |
  54. | Nodes (3) | `nodes_list`, `nodes_get`, `nodes_tags_list` |
  55. | Hosts (3) | `hosts_list`, `hosts_get`, `hosts_tags_list` |
  56. | System (10) | all tools (read-only by nature) |
  57. | Subscriptions (10) | all tools (read-only by nature) |
  58. | Config Profiles & Inbounds (5) | `config_profiles_list`, `config_profiles_get`, `inbounds_list`, `config_profiles_get_inbounds`, `config_profiles_get_computed_config` |
  59. | Internal Squads (2) | `squads_list`, `squads_accessible_nodes` |
  60. | HWID (4) | `hwid_devices_list`, `hwid_devices_list_all`, `hwid_stats`, `hwid_top_users` |
  61. | API Tokens (1) | `api_tokens_list` |
  62. | Keygen (1) | `keygen_get` |
  63. | Infra Billing (4) | `billing_providers_list`, `billing_provider_get`, `billing_nodes_list`, `billing_history_list` |
  64. | Snippets (1) | `snippets_list` |
  65. | External Squads (2) | `external_squads_list`, `external_squads_get` |
  66. | Settings (1) | `settings_get` |
  67. | Sub Page Configs (2) | `sub_page_configs_list`, `sub_page_configs_get` |
  68. | Node Plugins (4) | `node_plugins_list`, `node_plugins_get`, `node_plugins_torrent_reports`, `node_plugins_torrent_stats` |
  69. | IP Control (4) | `ip_control_fetch_ips`, `ip_control_get_fetch_ips_result`, `ip_control_fetch_users_ips`, `ip_control_get_fetch_users_ips_result` |
  70. | Metadata (2) | `metadata_node_get`, `metadata_user_get` |
  71. ### Usage with Claude Desktop
  72. Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
  73. ```json
  74. {
  75. "mcpServers": {
  76. "remnawave": {
  77. "command": "node",
  78. "args": ["/absolute/path/to/remnawave-mcp/dist/index.js"],
  79. "env": {
  80. "REMNAWAVE_BASE_URL": "https://vpn.example.com",
  81. "REMNAWAVE_API_TOKEN": "your-api-token-here",
  82. "REMNAWAVE_API_KEY": "your-caddy-api-key",
  83. "REMNAWAVE_READONLY": "false"
  84. }
  85. }
  86. }
  87. }
  88. ```
  89. ### Usage with Cursor / Windsurf
  90. Add to `.cursor/mcp.json` or `.windsurf/mcp.json` in your project:
  91. ```json
  92. {
  93. "mcpServers": {
  94. "remnawave": {
  95. "command": "node",
  96. "args": ["/absolute/path/to/remnawave-mcp/dist/index.js"],
  97. "env": {
  98. "REMNAWAVE_BASE_URL": "https://vpn.example.com",
  99. "REMNAWAVE_API_TOKEN": "your-api-token-here",
  100. "REMNAWAVE_API_KEY": "your-caddy-api-key",
  101. "REMNAWAVE_READONLY": "false"
  102. }
  103. }
  104. }
  105. }
  106. ```
  107. ### Docker
  108. ```bash
  109. npm run build
  110. docker compose up -d
  111. ```
  112. Environment variables are passed via `.env` file or `docker-compose.yml`.
  113. ### Available Tools
  114. #### Users (27 tools)
  115. | Tool | Description | Mode |
  116. |------|-------------|------|
  117. | `users_list` | List all users with pagination | read |
  118. | `users_get` | Get user by UUID | read |
  119. | `users_get_by_username` | Get user by username | read |
  120. | `users_get_by_short_uuid` | Get user by short UUID | read |
  121. | `users_get_by_telegram_id` | Get user by Telegram ID | read |
  122. | `users_get_by_email` | Get user by email | read |
  123. | `users_get_by_tag` | Get user by tag | read |
  124. | `users_get_by_subscription_uuid` | Get user by subscription UUID | read |
  125. | `users_tags_list` | List all user tags | read |
  126. | `users_resolve` | Resolve users by multiple criteria | read |
  127. | `users_create` | Create a new user | write |
  128. | `users_update` | Update user settings | write |
  129. | `users_delete` | Delete a user | write |
  130. | `users_enable` | Enable a disabled user | write |
  131. | `users_disable` | Disable a user | write |
  132. | `users_revoke_subscription` | Revoke subscription (regenerate link) | write |
  133. | `users_reset_traffic` | Reset traffic counter | write |
  134. | `users_bulk_delete_by_status` | Bulk delete users by status | write |
  135. | `users_bulk_update` | Bulk update users | write |
  136. | `users_bulk_reset_traffic` | Bulk reset traffic | write |
  137. | `users_bulk_revoke_subscription` | Bulk revoke subscriptions | write |
  138. | `users_bulk_delete` | Bulk delete users | write |
  139. | `users_bulk_update_squads` | Bulk update user squads | write |
  140. | `users_bulk_extend_expiration` | Bulk extend expiration dates | write |
  141. | `users_bulk_all_update` | Bulk update all users | write |
  142. | `users_bulk_all_reset_traffic` | Bulk reset all users traffic | write |
  143. | `users_bulk_all_extend_expiration` | Bulk extend all users expiration | write |
  144. #### Nodes (15 tools)
  145. | Tool | Description | Mode |
  146. |------|-------------|------|
  147. | `nodes_list` | List all nodes | read |
  148. | `nodes_get` | Get node by UUID | read |
  149. | `nodes_tags_list` | List all node tags | read |
  150. | `nodes_create` | Create a new node | write |
  151. | `nodes_update` | Update node settings | write |
  152. | `nodes_delete` | Delete a node | write |
  153. | `nodes_enable` | Enable a node | write |
  154. | `nodes_disable` | Disable a node | write |
  155. | `nodes_restart` | Restart a specific node | write |
  156. | `nodes_restart_all` | Restart all nodes | write |
  157. | `nodes_reset_traffic` | Reset node traffic counter | write |
  158. | `nodes_reorder` | Reorder nodes | write |
  159. | `nodes_bulk_profile_modification` | Bulk modify node profiles | write |
  160. | `nodes_bulk_actions` | Bulk node actions | write |
  161. | `nodes_bulk_update` | Bulk update nodes | write |
  162. #### Hosts (11 tools)
  163. | Tool | Description | Mode |
  164. |------|-------------|------|
  165. | `hosts_list` | List all hosts | read |
  166. | `hosts_get` | Get host by UUID | read |
  167. | `hosts_tags_list` | List all host tags | read |
  168. | `hosts_create` | Create a new host | write |
  169. | `hosts_update` | Update host settings | write |
  170. | `hosts_delete` | Delete a host | write |
  171. | `hosts_bulk_enable` | Bulk enable hosts | write |
  172. | `hosts_bulk_disable` | Bulk disable hosts | write |
  173. | `hosts_bulk_delete` | Bulk delete hosts | write |
  174. | `hosts_bulk_set_inbound` | Bulk set host inbound | write |
  175. | `hosts_bulk_set_port` | Bulk set host port | write |
  176. #### System (10 tools)
  177. | Tool | Description | Mode |
  178. |------|-------------|------|
  179. | `system_stats` | Panel statistics (users, nodes, traffic, CPU, memory) | read |
  180. | `system_bandwidth_stats` | Bandwidth statistics | read |
  181. | `system_nodes_metrics` | Node metrics | read |
  182. | `system_nodes_statistics` | Node statistics | read |
  183. | `system_health` | Panel health check | read |
  184. | `system_metadata` | Panel version and metadata | read |
  185. | `system_generate_x25519` | Generate X25519 key pair | read |
  186. | `auth_status` | Check authentication status | read |
  187. | `system_stats_recap` | System statistics recap | read |
  188. | `system_srr_matcher` | Test SRR routing rules | read |
  189. #### Subscriptions (10 tools)
  190. | Tool | Description | Mode |
  191. |------|-------------|------|
  192. | `subscriptions_list` | List all subscriptions | read |
  193. | `subscriptions_get_by_uuid` | Get subscription by UUID | read |
  194. | `subscriptions_get_by_username` | Get subscription by username | read |
  195. | `subscriptions_get_by_short_uuid` | Get subscription by short UUID | read |
  196. | `subscriptions_get_raw_by_short_uuid` | Get raw subscription by short UUID | read |
  197. | `subscriptions_get_subpage_config` | Get subscription subpage config | read |
  198. | `subscriptions_get_connection_keys` | Get connection keys by UUID | read |
  199. | `subscription_info` | Get subscription info | read |
  200. | `subscription_request_history_list` | Subscription request history | read |
  201. | `subscription_request_history_stats` | Subscription request history stats | read |
  202. #### Config Profiles & Inbounds (9 tools)
  203. | Tool | Description | Mode |
  204. |------|-------------|------|
  205. | `config_profiles_list` | List config profiles | read |
  206. | `config_profiles_get` | Get config profile by UUID | read |
  207. | `inbounds_list` | List all inbounds | read |
  208. | `config_profiles_get_inbounds` | Get inbounds by profile UUID | read |
  209. | `config_profiles_get_computed_config` | Get computed config by profile UUID | read |
  210. | `config_profiles_create` | Create config profile | write |
  211. | `config_profiles_update` | Update config profile | write |
  212. | `config_profiles_delete` | Delete config profile | write |
  213. | `config_profiles_reorder` | Reorder config profiles | write |
  214. #### Internal Squads (7 tools)
  215. | Tool | Description | Mode |
  216. |------|-------------|------|
  217. | `squads_list` | List all squads | read |
  218. | `squads_accessible_nodes` | Get squad accessible nodes | read |
  219. | `squads_create` | Create a squad | write |
  220. | `squads_update` | Update a squad | write |
  221. | `squads_delete` | Delete a squad | write |
  222. | `squads_add_users` | Add users to a squad | write |
  223. | `squads_remove_users` | Remove users from a squad | write |
  224. #### HWID Devices (7 tools)
  225. | Tool | Description | Mode |
  226. |------|-------------|------|
  227. | `hwid_devices_list` | List user's HWID devices | read |
  228. | `hwid_devices_list_all` | List all HWID devices | read |
  229. | `hwid_stats` | Get HWID statistics | read |
  230. | `hwid_top_users` | Get top users by devices | read |
  231. | `hwid_device_create` | Create HWID device | write |
  232. | `hwid_device_delete` | Delete a specific device | write |
  233. | `hwid_devices_delete_all` | Delete all user's devices | write |
  234. #### API Tokens (3 tools)
  235. | Tool | Description | Mode |
  236. |------|-------------|------|
  237. | `api_tokens_list` | List API tokens | read |
  238. | `api_tokens_create` | Create API token | write |
  239. | `api_tokens_delete` | Delete API token | write |
  240. #### Keygen (1 tool)
  241. | Tool | Description | Mode |
  242. |------|-------------|------|
  243. | `keygen_get` | Get keygen data | read |
  244. #### Infra Billing (12 tools)
  245. | Tool | Description | Mode |
  246. |------|-------------|------|
  247. | `billing_providers_list` | List billing providers | read |
  248. | `billing_provider_get` | Get billing provider by UUID | read |
  249. | `billing_nodes_list` | List billing nodes | read |
  250. | `billing_history_list` | List billing history | read |
  251. | `billing_provider_create` | Create billing provider | write |
  252. | `billing_provider_update` | Update billing provider | write |
  253. | `billing_provider_delete` | Delete billing provider | write |
  254. | `billing_node_create` | Create billing node | write |
  255. | `billing_node_update` | Update billing node | write |
  256. | `billing_node_delete` | Delete billing node | write |
  257. | `billing_history_create` | Create billing history entry | write |
  258. | `billing_history_delete` | Delete billing history entry | write |
  259. #### Snippets (4 tools)
  260. | Tool | Description | Mode |
  261. |------|-------------|------|
  262. | `snippets_list` | List snippets | read |
  263. | `snippets_create` | Create snippet | write |
  264. | `snippets_update` | Update snippet | write |
  265. | `snippets_delete` | Delete snippet | write |
  266. #### External Squads (8 tools)
  267. | Tool | Description | Mode |
  268. |------|-------------|------|
  269. | `external_squads_list` | List external squads | read |
  270. | `external_squads_get` | Get external squad by UUID | read |
  271. | `external_squads_create` | Create external squad | write |
  272. | `external_squads_update` | Update external squad | write |
  273. | `external_squads_delete` | Delete external squad | write |
  274. | `external_squads_add_users` | Add users to external squad | write |
  275. | `external_squads_remove_users` | Remove users from external squad | write |
  276. | `external_squads_reorder` | Reorder external squads | write |
  277. #### Settings (2 tools)
  278. | Tool | Description | Mode |
  279. |------|-------------|------|
  280. | `settings_get` | Get panel settings | read |
  281. | `settings_update` | Update panel settings | write |
  282. #### Subscription Page Configs (7 tools)
  283. | Tool | Description | Mode |
  284. |------|-------------|------|
  285. | `sub_page_configs_list` | List subscription page configs | read |
  286. | `sub_page_configs_get` | Get subscription page config | read |
  287. | `sub_page_configs_create` | Create subscription page config | write |
  288. | `sub_page_configs_update` | Update subscription page config | write |
  289. | `sub_page_configs_delete` | Delete subscription page config | write |
  290. | `sub_page_configs_reorder` | Reorder subscription page configs | write |
  291. | `sub_page_configs_clone` | Clone subscription page config | write |
  292. #### Node Plugins (11 tools)
  293. | Tool | Description | Mode |
  294. |------|-------------|------|
  295. | `node_plugins_list` | List node plugins | read |
  296. | `node_plugins_get` | Get node plugin by UUID | read |
  297. | `node_plugins_torrent_reports` | Get torrent blocker reports | read |
  298. | `node_plugins_torrent_stats` | Get torrent blocker stats | read |
  299. | `node_plugins_create` | Create node plugin | write |
  300. | `node_plugins_update` | Update node plugin | write |
  301. | `node_plugins_delete` | Delete node plugin | write |
  302. | `node_plugins_reorder` | Reorder node plugins | write |
  303. | `node_plugins_clone` | Clone node plugin | write |
  304. | `node_plugins_execute` | Execute node plugin | write |
  305. | `node_plugins_torrent_truncate` | Truncate torrent blocker reports | write |
  306. #### IP Control (5 tools)
  307. | Tool | Description | Mode |
  308. |------|-------------|------|
  309. | `ip_control_fetch_ips` | Fetch IPs for a user | read |
  310. | `ip_control_get_fetch_ips_result` | Get fetch IPs job result | read |
  311. | `ip_control_fetch_users_ips` | Fetch users IPs on a node | read |
  312. | `ip_control_get_fetch_users_ips_result` | Get fetch users IPs job result | read |
  313. | `ip_control_drop_connections` | Drop user connections | write |
  314. #### Metadata (4 tools)
  315. | Tool | Description | Mode |
  316. |------|-------------|------|
  317. | `metadata_node_get` | Get node metadata | read |
  318. | `metadata_user_get` | Get user metadata | read |
  319. | `metadata_node_upsert` | Upsert node metadata | write |
  320. | `metadata_user_upsert` | Upsert user metadata | write |
  321. ### Resources
  322. | URI | Description |
  323. |-----|-------------|
  324. | `remnawave://stats` | Current panel statistics |
  325. | `remnawave://nodes` | All nodes status |
  326. | `remnawave://health` | Panel health status |
  327. | `remnawave://users/{uuid}` | Specific user details |
  328. ### Prompts
  329. | Prompt | Description |
  330. |--------|-------------|
  331. | `create_user_wizard` | Step-by-step user creation guide |
  332. | `node_diagnostics` | Node troubleshooting |
  333. | `traffic_report` | Traffic usage report |
  334. | `user_audit` | Complete user audit |
  335. | `bulk_user_cleanup` | Find and manage expired users |
  336. ### Example Queries
  337. ```
  338. "Show me all users with expired subscriptions"
  339. "Create user vasya with 50 GB limit for one month"
  340. "Restart node amsterdam-01"
  341. "Give me a traffic report for the last week"
  342. "Disable users who exceeded their traffic limit"
  343. "Which nodes are offline right now?"
  344. "Show billing history"
  345. "List all node plugins"
  346. "Get IP connections for user X"
  347. ```
  348. ### Project Structure
  349. ```
  350. src/
  351. ├── index.ts # Entry point (stdio transport)
  352. ├── server.ts # McpServer setup
  353. ├── config.ts # Environment config
  354. ├── client/
  355. │ └── index.ts # Remnawave HTTP client
  356. ├── tools/
  357. │ ├── helpers.ts # Result formatting helpers
  358. │ ├── index.ts # Tool registration
  359. │ ├── users.ts # User management (27 tools)
  360. │ ├── nodes.ts # Node management (15 tools)
  361. │ ├── hosts.ts # Host management (11 tools)
  362. │ ├── system.ts # System & auth (10 tools)
  363. │ ├── subscriptions.ts # Subscriptions (10 tools)
  364. │ ├── inbounds.ts # Config profiles & inbounds (9 tools)
  365. │ ├── squads.ts # Internal squads (7 tools)
  366. │ ├── hwid.ts # HWID devices (7 tools)
  367. │ ├── infra-billing.ts # Infrastructure billing (12 tools)
  368. │ ├── node-plugins.ts # Node plugins (11 tools)
  369. │ ├── external-squads.ts # External squads (8 tools)
  370. │ ├── subscription-page-configs.ts # Subscription page configs (7 tools)
  371. │ ├── ip-control.ts # IP control (5 tools)
  372. │ ├── snippets.ts # Snippets (4 tools)
  373. │ ├── metadata.ts # Node & user metadata (4 tools)
  374. │ ├── api-tokens.ts # API tokens (3 tools)
  375. │ ├── settings.ts # Panel settings (2 tools)
  376. │ └── keygen.ts # Keygen (1 tool)
  377. ├── resources/
  378. │ └── index.ts # MCP resources
  379. └── prompts/
  380. └── index.ts # MCP prompts
  381. ```
  382. ### License
  383. MIT
  384. ---
  385. <a id="русский"></a>
  386. ## MCP-сервер для Remnawave Panel
  387. MCP-сервер ([Model Context Protocol](https://modelcontextprotocol.io)), предоставляющий LLM-клиентам (Claude Desktop, Cursor, Windsurf и др.) инструменты для управления VPN-панелью [Remnawave](https://github.com/remnawave/).
  388. **Версия:** 1.2.0 | **Remnawave API:** 2.7.4
  389. ### Возможности
  390. - **153 инструмента** — полное управление пользователями, нодами, хостами, подписками, группами, HWID, конфиг-профилями, inbounds, API-токенами, биллингом, сниппетами, внешними группами, настройками, страницами подписок, плагинами нод, IP-контролем и метаданными
  391. - **3 ресурса** — статистика панели, статус нод, проверка здоровья в реальном времени
  392. - **5 промптов** — пошаговые сценарии для типичных задач
  393. - **Readonly-режим** — ограничение до 69 инструментов только для чтения
  394. - **Поддержка Caddy** — заголовок `X-Api-Key` для панелей за Caddy с кастомным путём
  395. - **Type-safe** — построен на [@remnawave/backend-contract](https://www.npmjs.com/package/@remnawave/backend-contract) для валидации API-маршрутов
  396. - **stdio транспорт** — работает с Claude Desktop, Cursor, Windsurf и любым MCP-совместимым клиентом
  397. ### Требования
  398. - Node.js >= 22
  399. - Remnawave панель с API-токеном (Настройки > API Tokens)
  400. ### Установка
  401. ```bash
  402. git clone https://github.com/TrackLine/mcp-remnawave.git
  403. cd mcp-remnawave
  404. npm install
  405. npm run build
  406. ```
  407. ### Конфигурация
  408. Создайте файл `.env` или передайте переменные окружения:
  409. | Переменная | Обязательная | Описание |
  410. |------------|-------------|----------|
  411. | `REMNAWAVE_BASE_URL` | Да | URL панели (например `https://vpn.example.com`) |
  412. | `REMNAWAVE_API_TOKEN` | Да | API-токен из настроек панели |
  413. | `REMNAWAVE_API_KEY` | Нет | API-ключ для аутентификации через Caddy reverse proxy |
  414. | `REMNAWAVE_READONLY` | Нет | `true` для включения режима только чтения |
  415. ```env
  416. REMNAWAVE_BASE_URL=https://vpn.example.com
  417. REMNAWAVE_API_TOKEN=ваш-api-токен
  418. ```
  419. ### Caddy с кастомным путём
  420. Если ваша панель Remnawave развёрнута за [Caddy с кастомным путём и защитой API-ключом](https://docs.remnawave.com/docs/security/caddy-with-custom-path/), укажите полный путь в base URL и предоставьте API-ключ:
  421. ```env
  422. REMNAWAVE_BASE_URL=https://example.com/your-secret-path/api
  423. REMNAWAVE_API_KEY=ваш-caddy-api-ключ
  424. ```
  425. Заголовок `X-Api-Key` будет автоматически добавляться к каждому запросу.
  426. ### Режим Readonly
  427. Установите `REMNAWAVE_READONLY=true`, чтобы отключить все операции записи (создание, обновление, удаление, включение, отключение, перезапуск, отзыв, сброс). Будут зарегистрированы только инструменты чтения.
  428. Полезно для мониторинговых дашбордов или общих окружений, где нужно исключить случайные изменения.
  429. В readonly-режиме количество доступных инструментов сокращается с 153 до 69:
  430. | Категория | Доступные инструменты |
  431. |-----------|----------------------|
  432. | Пользователи (10) | `users_list`, `users_get`, `users_get_by_username`, `users_get_by_short_uuid`, `users_get_by_telegram_id`, `users_get_by_email`, `users_get_by_tag`, `users_get_by_subscription_uuid`, `users_tags_list`, `users_resolve` |
  433. | Ноды (3) | `nodes_list`, `nodes_get`, `nodes_tags_list` |
  434. | Хосты (3) | `hosts_list`, `hosts_get`, `hosts_tags_list` |
  435. | Система (10) | все инструменты (только чтение по природе) |
  436. | Подписки (10) | все инструменты (только чтение по природе) |
  437. | Конфиг-профили и Inbounds (5) | `config_profiles_list`, `config_profiles_get`, `inbounds_list`, `config_profiles_get_inbounds`, `config_profiles_get_computed_config` |
  438. | Внутренние группы (2) | `squads_list`, `squads_accessible_nodes` |
  439. | HWID (4) | `hwid_devices_list`, `hwid_devices_list_all`, `hwid_stats`, `hwid_top_users` |
  440. | API-токены (1) | `api_tokens_list` |
  441. | Keygen (1) | `keygen_get` |
  442. | Биллинг (4) | `billing_providers_list`, `billing_provider_get`, `billing_nodes_list`, `billing_history_list` |
  443. | Сниппеты (1) | `snippets_list` |
  444. | Внешние группы (2) | `external_squads_list`, `external_squads_get` |
  445. | Настройки (1) | `settings_get` |
  446. | Страницы подписок (2) | `sub_page_configs_list`, `sub_page_configs_get` |
  447. | Плагины нод (4) | `node_plugins_list`, `node_plugins_get`, `node_plugins_torrent_reports`, `node_plugins_torrent_stats` |
  448. | IP-контроль (4) | `ip_control_fetch_ips`, `ip_control_get_fetch_ips_result`, `ip_control_fetch_users_ips`, `ip_control_get_fetch_users_ips_result` |
  449. | Метаданные (2) | `metadata_node_get`, `metadata_user_get` |
  450. ### Использование с Claude Desktop
  451. Добавьте в конфигурацию Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` на macOS):
  452. ```json
  453. {
  454. "mcpServers": {
  455. "remnawave": {
  456. "command": "node",
  457. "args": ["/абсолютный/путь/к/remnawave-mcp/dist/index.js"],
  458. "env": {
  459. "REMNAWAVE_BASE_URL": "https://vpn.example.com",
  460. "REMNAWAVE_API_TOKEN": "ваш-api-токен",
  461. "REMNAWAVE_API_KEY": "ваш-caddy-api-ключ",
  462. "REMNAWAVE_READONLY": "false"
  463. }
  464. }
  465. }
  466. }
  467. ```
  468. ### Использование с Cursor / Windsurf
  469. Добавьте в `.cursor/mcp.json` или `.windsurf/mcp.json` вашего проекта:
  470. ```json
  471. {
  472. "mcpServers": {
  473. "remnawave": {
  474. "command": "node",
  475. "args": ["/абсолютный/путь/к/remnawave-mcp/dist/index.js"],
  476. "env": {
  477. "REMNAWAVE_BASE_URL": "https://vpn.example.com",
  478. "REMNAWAVE_API_TOKEN": "ваш-api-токен",
  479. "REMNAWAVE_API_KEY": "ваш-caddy-api-ключ",
  480. "REMNAWAVE_READONLY": "false"
  481. }
  482. }
  483. }
  484. }
  485. ```
  486. ### Docker
  487. ```bash
  488. npm run build
  489. docker compose up -d
  490. ```
  491. Переменные окружения передаются через `.env` файл или `docker-compose.yml`.
  492. ### Доступные инструменты
  493. #### Пользователи (27 инструментов)
  494. | Инструмент | Описание | Режим |
  495. |------------|----------|-------|
  496. | `users_list` | Список пользователей с пагинацией | read |
  497. | `users_get` | Получить пользователя по UUID | read |
  498. | `users_get_by_username` | Получить пользователя по username | read |
  499. | `users_get_by_short_uuid` | Получить пользователя по short UUID | read |
  500. | `users_get_by_telegram_id` | Получить пользователя по Telegram ID | read |
  501. | `users_get_by_email` | Получить пользователя по email | read |
  502. | `users_get_by_tag` | Получить пользователя по тегу | read |
  503. | `users_get_by_subscription_uuid` | Получить пользователя по UUID подписки | read |
  504. | `users_tags_list` | Список тегов пользователей | read |
  505. | `users_resolve` | Поиск пользователей по нескольким критериям | read |
  506. | `users_create` | Создать нового пользователя | write |
  507. | `users_update` | Обновить настройки пользователя | write |
  508. | `users_delete` | Удалить пользователя | write |
  509. | `users_enable` | Включить пользователя | write |
  510. | `users_disable` | Отключить пользователя | write |
  511. | `users_revoke_subscription` | Отозвать подписку (перегенерировать ссылку) | write |
  512. | `users_reset_traffic` | Сбросить счётчик трафика | write |
  513. | `users_bulk_delete_by_status` | Массовое удаление по статусу | write |
  514. | `users_bulk_update` | Массовое обновление | write |
  515. | `users_bulk_reset_traffic` | Массовый сброс трафика | write |
  516. | `users_bulk_revoke_subscription` | Массовый отзыв подписок | write |
  517. | `users_bulk_delete` | Массовое удаление | write |
  518. | `users_bulk_update_squads` | Массовое обновление групп | write |
  519. | `users_bulk_extend_expiration` | Массовое продление срока | write |
  520. | `users_bulk_all_update` | Обновить всех пользователей | write |
  521. | `users_bulk_all_reset_traffic` | Сбросить трафик всех пользователей | write |
  522. | `users_bulk_all_extend_expiration` | Продлить срок всех пользователей | write |
  523. #### Ноды (15 инструментов)
  524. | Инструмент | Описание | Режим |
  525. |------------|----------|-------|
  526. | `nodes_list` | Список всех нод | read |
  527. | `nodes_get` | Получить ноду по UUID | read |
  528. | `nodes_tags_list` | Список тегов нод | read |
  529. | `nodes_create` | Создать новую ноду | write |
  530. | `nodes_update` | Обновить настройки ноды | write |
  531. | `nodes_delete` | Удалить ноду | write |
  532. | `nodes_enable` | Включить ноду | write |
  533. | `nodes_disable` | Отключить ноду | write |
  534. | `nodes_restart` | Перезапустить ноду | write |
  535. | `nodes_restart_all` | Перезапустить все ноды | write |
  536. | `nodes_reset_traffic` | Сбросить трафик ноды | write |
  537. | `nodes_reorder` | Переупорядочить ноды | write |
  538. | `nodes_bulk_profile_modification` | Массовое изменение профилей нод | write |
  539. | `nodes_bulk_actions` | Массовые действия с нодами | write |
  540. | `nodes_bulk_update` | Массовое обновление нод | write |
  541. #### Хосты (11 инструментов)
  542. | Инструмент | Описание | Режим |
  543. |------------|----------|-------|
  544. | `hosts_list` | Список всех хостов | read |
  545. | `hosts_get` | Получить хост по UUID | read |
  546. | `hosts_tags_list` | Список тегов хостов | read |
  547. | `hosts_create` | Создать новый хост | write |
  548. | `hosts_update` | Обновить настройки хоста | write |
  549. | `hosts_delete` | Удалить хост | write |
  550. | `hosts_bulk_enable` | Массовое включение хостов | write |
  551. | `hosts_bulk_disable` | Массовое отключение хостов | write |
  552. | `hosts_bulk_delete` | Массовое удаление хостов | write |
  553. | `hosts_bulk_set_inbound` | Массовая установка inbound | write |
  554. | `hosts_bulk_set_port` | Массовая установка порта | write |
  555. #### Система (10 инструментов)
  556. | Инструмент | Описание | Режим |
  557. |------------|----------|-------|
  558. | `system_stats` | Статистика панели (пользователи, ноды, трафик, CPU, память) | read |
  559. | `system_bandwidth_stats` | Статистика пропускной способности | read |
  560. | `system_nodes_metrics` | Метрики нод | read |
  561. | `system_nodes_statistics` | Статистика нод | read |
  562. | `system_health` | Проверка здоровья панели | read |
  563. | `system_metadata` | Версия и метаданные панели | read |
  564. | `system_generate_x25519` | Генерация пары ключей X25519 | read |
  565. | `auth_status` | Проверка статуса аутентификации | read |
  566. | `system_stats_recap` | Обзор статистики | read |
  567. | `system_srr_matcher` | Тест SRR-правил маршрутизации | read |
  568. #### Подписки (10 инструментов)
  569. | Инструмент | Описание | Режим |
  570. |------------|----------|-------|
  571. | `subscriptions_list` | Список всех подписок | read |
  572. | `subscriptions_get_by_uuid` | Подписка по UUID | read |
  573. | `subscriptions_get_by_username` | Подписка по username | read |
  574. | `subscriptions_get_by_short_uuid` | Подписка по short UUID | read |
  575. | `subscriptions_get_raw_by_short_uuid` | Сырая подписка по short UUID | read |
  576. | `subscriptions_get_subpage_config` | Конфиг субстраницы подписки | read |
  577. | `subscriptions_get_connection_keys` | Ключи подключения по UUID | read |
  578. | `subscription_info` | Информация о подписке | read |
  579. | `subscription_request_history_list` | История запросов подписок | read |
  580. | `subscription_request_history_stats` | Статистика запросов подписок | read |
  581. #### Конфиг-профили и Inbounds (9 инструментов)
  582. | Инструмент | Описание | Режим |
  583. |------------|----------|-------|
  584. | `config_profiles_list` | Список конфиг-профилей | read |
  585. | `config_profiles_get` | Получить конфиг-профиль по UUID | read |
  586. | `inbounds_list` | Список всех inbounds | read |
  587. | `config_profiles_get_inbounds` | Inbounds по UUID профиля | read |
  588. | `config_profiles_get_computed_config` | Вычисленный конфиг по UUID профиля | read |
  589. | `config_profiles_create` | Создать конфиг-профиль | write |
  590. | `config_profiles_update` | Обновить конфиг-профиль | write |
  591. | `config_profiles_delete` | Удалить конфиг-профиль | write |
  592. | `config_profiles_reorder` | Переупорядочить конфиг-профили | write |
  593. #### Внутренние группы (7 инструментов)
  594. | Инструмент | Описание | Режим |
  595. |------------|----------|-------|
  596. | `squads_list` | Список групп | read |
  597. | `squads_accessible_nodes` | Доступные ноды группы | read |
  598. | `squads_create` | Создать группу | write |
  599. | `squads_update` | Обновить группу | write |
  600. | `squads_delete` | Удалить группу | write |
  601. | `squads_add_users` | Добавить пользователей в группу | write |
  602. | `squads_remove_users` | Убрать пользователей из группы | write |
  603. #### HWID-устройства (7 инструментов)
  604. | Инструмент | Описание | Режим |
  605. |------------|----------|-------|
  606. | `hwid_devices_list` | Список устройств пользователя | read |
  607. | `hwid_devices_list_all` | Список всех устройств | read |
  608. | `hwid_stats` | Статистика HWID | read |
  609. | `hwid_top_users` | Топ пользователей по устройствам | read |
  610. | `hwid_device_create` | Создать HWID-устройство | write |
  611. | `hwid_device_delete` | Удалить конкретное устройство | write |
  612. | `hwid_devices_delete_all` | Удалить все устройства пользователя | write |
  613. #### API-токены (3 инструмента)
  614. | Инструмент | Описание | Режим |
  615. |------------|----------|-------|
  616. | `api_tokens_list` | Список API-токенов | read |
  617. | `api_tokens_create` | Создать API-токен | write |
  618. | `api_tokens_delete` | Удалить API-токен | write |
  619. #### Keygen (1 инструмент)
  620. | Инструмент | Описание | Режим |
  621. |------------|----------|-------|
  622. | `keygen_get` | Получить данные keygen | read |
  623. #### Биллинг инфраструктуры (12 инструментов)
  624. | Инструмент | Описание | Режим |
  625. |------------|----------|-------|
  626. | `billing_providers_list` | Список провайдеров биллинга | read |
  627. | `billing_provider_get` | Получить провайдера по UUID | read |
  628. | `billing_nodes_list` | Список биллинговых нод | read |
  629. | `billing_history_list` | История биллинга | read |
  630. | `billing_provider_create` | Создать провайдера | write |
  631. | `billing_provider_update` | Обновить провайдера | write |
  632. | `billing_provider_delete` | Удалить провайдера | write |
  633. | `billing_node_create` | Создать биллинговую ноду | write |
  634. | `billing_node_update` | Обновить биллинговую ноду | write |
  635. | `billing_node_delete` | Удалить биллинговую ноду | write |
  636. | `billing_history_create` | Создать запись истории | write |
  637. | `billing_history_delete` | Удалить запись истории | write |
  638. #### Сниппеты (4 инструмента)
  639. | Инструмент | Описание | Режим |
  640. |------------|----------|-------|
  641. | `snippets_list` | Список сниппетов | read |
  642. | `snippets_create` | Создать сниппет | write |
  643. | `snippets_update` | Обновить сниппет | write |
  644. | `snippets_delete` | Удалить сниппет | write |
  645. #### Внешние группы (8 инструментов)
  646. | Инструмент | Описание | Режим |
  647. |------------|----------|-------|
  648. | `external_squads_list` | Список внешних групп | read |
  649. | `external_squads_get` | Получить внешнюю группу по UUID | read |
  650. | `external_squads_create` | Создать внешнюю группу | write |
  651. | `external_squads_update` | Обновить внешнюю группу | write |
  652. | `external_squads_delete` | Удалить внешнюю группу | write |
  653. | `external_squads_add_users` | Добавить пользователей | write |
  654. | `external_squads_remove_users` | Убрать пользователей | write |
  655. | `external_squads_reorder` | Переупорядочить | write |
  656. #### Настройки (2 инструмента)
  657. | Инструмент | Описание | Режим |
  658. |------------|----------|-------|
  659. | `settings_get` | Получить настройки панели | read |
  660. | `settings_update` | Обновить настройки панели | write |
  661. #### Страницы подписок (7 инструментов)
  662. | Инструмент | Описание | Режим |
  663. |------------|----------|-------|
  664. | `sub_page_configs_list` | Список конфигов страниц | read |
  665. | `sub_page_configs_get` | Получить конфиг страницы | read |
  666. | `sub_page_configs_create` | Создать конфиг страницы | write |
  667. | `sub_page_configs_update` | Обновить конфиг страницы | write |
  668. | `sub_page_configs_delete` | Удалить конфиг страницы | write |
  669. | `sub_page_configs_reorder` | Переупорядочить | write |
  670. | `sub_page_configs_clone` | Клонировать конфиг | write |
  671. #### Плагины нод (11 инструментов)
  672. | Инструмент | Описание | Режим |
  673. |------------|----------|-------|
  674. | `node_plugins_list` | Список плагинов | read |
  675. | `node_plugins_get` | Получить плагин по UUID | read |
  676. | `node_plugins_torrent_reports` | Отчёты торрент-блокировщика | read |
  677. | `node_plugins_torrent_stats` | Статистика торрент-блокировщика | read |
  678. | `node_plugins_create` | Создать плагин | write |
  679. | `node_plugins_update` | Обновить плагин | write |
  680. | `node_plugins_delete` | Удалить плагин | write |
  681. | `node_plugins_reorder` | Переупорядочить плагины | write |
  682. | `node_plugins_clone` | Клонировать плагин | write |
  683. | `node_plugins_execute` | Выполнить плагин | write |
  684. | `node_plugins_torrent_truncate` | Очистить отчёты торрент-блокировщика | write |
  685. #### IP-контроль (5 инструментов)
  686. | Инструмент | Описание | Режим |
  687. |------------|----------|-------|
  688. | `ip_control_fetch_ips` | Получить IP пользователя | read |
  689. | `ip_control_get_fetch_ips_result` | Результат запроса IP | read |
  690. | `ip_control_fetch_users_ips` | Получить IP пользователей на ноде | read |
  691. | `ip_control_get_fetch_users_ips_result` | Результат запроса IP пользователей | read |
  692. | `ip_control_drop_connections` | Сбросить соединения | write |
  693. #### Метаданные (4 инструмента)
  694. | Инструмент | Описание | Режим |
  695. |------------|----------|-------|
  696. | `metadata_node_get` | Получить метаданные ноды | read |
  697. | `metadata_user_get` | Получить метаданные пользователя | read |
  698. | `metadata_node_upsert` | Обновить метаданные ноды | write |
  699. | `metadata_user_upsert` | Обновить метаданные пользователя | write |
  700. ### Ресурсы
  701. | URI | Описание |
  702. |-----|----------|
  703. | `remnawave://stats` | Текущая статистика панели |
  704. | `remnawave://nodes` | Статус всех нод |
  705. | `remnawave://health` | Состояние здоровья панели |
  706. | `remnawave://users/{uuid}` | Данные конкретного пользователя |
  707. ### Промпты
  708. | Промпт | Описание |
  709. |--------|----------|
  710. | `create_user_wizard` | Пошаговое создание пользователя |
  711. | `node_diagnostics` | Диагностика ноды |
  712. | `traffic_report` | Отчёт по трафику |
  713. | `user_audit` | Полный аудит пользователя |
  714. | `bulk_user_cleanup` | Поиск и управление просроченными пользователями |
  715. ### Примеры запросов
  716. ```
  717. «Покажи мне всех пользователей с истёкшей подпиской»
  718. «Создай пользователя vasya с лимитом 50 ГБ на месяц»
  719. «Перезапусти ноду amsterdam-01»
  720. «Дай отчёт по трафику за последнюю неделю»
  721. «Отключи пользователей, которые превысили лимит трафика»
  722. «Какие ноды сейчас офлайн?»
  723. «Покажи историю биллинга»
  724. «Список плагинов нод»
  725. «Получи IP-соединения пользователя X»
  726. ```
  727. ### Структура проекта
  728. ```
  729. src/
  730. ├── index.ts # Точка входа (stdio транспорт)
  731. ├── server.ts # Настройка McpServer
  732. ├── config.ts # Конфигурация окружения
  733. ├── client/
  734. │ └── index.ts # HTTP-клиент Remnawave
  735. ├── tools/
  736. │ ├── helpers.ts # Хелперы форматирования
  737. │ ├── index.ts # Регистрация инструментов
  738. │ ├── users.ts # Управление пользователями (27)
  739. │ ├── nodes.ts # Управление нодами (15)
  740. │ ├── hosts.ts # Управление хостами (11)
  741. │ ├── system.ts # Система и авторизация (10)
  742. │ ├── subscriptions.ts # Подписки (10)
  743. │ ├── inbounds.ts # Конфиг-профили и inbounds (9)
  744. │ ├── squads.ts # Внутренние группы (7)
  745. │ ├── hwid.ts # HWID-устройства (7)
  746. │ ├── infra-billing.ts # Биллинг инфраструктуры (12)
  747. │ ├── node-plugins.ts # Плагины нод (11)
  748. │ ├── external-squads.ts # Внешние группы (8)
  749. │ ├── subscription-page-configs.ts # Страницы подписок (7)
  750. │ ├── ip-control.ts # IP-контроль (5)
  751. │ ├── snippets.ts # Сниппеты (4)
  752. │ ├── metadata.ts # Метаданные нод и пользователей (4)
  753. │ ├── api-tokens.ts # API-токены (3)
  754. │ ├── settings.ts # Настройки панели (2)
  755. │ └── keygen.ts # Keygen (1)
  756. ├── resources/
  757. │ └── index.ts # MCP-ресурсы
  758. └── prompts/
  759. └── index.ts # MCP-промпты
  760. ```
  761. ### Лицензия
  762. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.