mcp-remnawave

MCP-сервер для VPN-панели Remnawave — обновлён для Remnawave 3.x

Английский · Русскиий

Позволяет MCP-клиенту — Claude Code, Claude Desktop, Cursor или любоому другоому — читать и управлять поолззователами, нодами, трафиком хостов, конфигурационными профилями, группами, шаблонами подписок, биллингом и HWID-устройствами через REST API панели.

Поддерживаемый форк TrackLine/mcp-remnawave v1.2.0, приведённый в соответствие с Remnawave 3.x (проверено противеь живой панели 3.3.x) и переработанный так, что схемы инструментов больше не могут рассинхронизироваться с API панели.

✨ Основные возможности

Related MCP server: remnawave-mcp-server

🚀 Быстрый старт

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"

Вот и все. Попросите вашего клиент вызвать system_metadata — он должен вернуть версию панели.

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

Любой stdio MCP-клиент — укажите ему node dist/index.js и передайте переменные окружения из таблицы вниз (или используйте поиск конфигурационного файла).

⚙️ Конфигурация

Откуда берётся конфигурация

Сервер останавливается на первом файле, который содержит REMNAWAVE_BASE_URL и 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

MCP-клиенты запускают stdio-серверы с cwd, установленным на корень проекта, поэтому при одной глобальной установке активная панель — та проект, в котором вы работаете. Чтобы добавить панель, положите .remnawave.env в её проект — на стороне сервера менять ничего не нужно. Переменные, уже присутствующие в окружении, никогда не перезаписываются, так что переменные, переданные клиентом при регистрации, всегда имеют приоритет.

Режим «только чтение»

Запустите с REMNAWAVE_READONLY=true. Инструменты записи (create / update / delete / enable / disable / bulk) в этом режиме не регистрируются вовсе, поэтому клиент не сможет даже пописать. Когда запись действительно нужна, установите false и перезапустите сервер.

🧰 Инструменты

Около 150 инструментов, сгруппированных так же, как в API панели. Инструменты чтения доступны всегда; инструменты записи — только когда режим «только чтения» отключён.

• Поиск по telegramId / email / тегу / статусу: users_list с filters: [{"id": "telegramId", "value": 123456789}] (+ опционально filterModes, sorting). Это заменяет удалённые маршруты by-* из 3.x.

• users_resolve принимает ровно один из id, shortUuid, username.

• Массовые инструменты принимают userIds: number[] (1–500); users_bulk_update вкладывает изменённые поля в fields.

• users_create также принимает явные vlessUuid / ssPassword / trojanPassword / shortUuid — удобно для сервисных учётных записей.

• config_profiles_update с config полностью заменяет весь xray-конфиг профиля — прочитайте, измените и напишите обратно.

• hosts_create требует inbound: { configProfileUuid, configProfileInboundUuid }.

api_tokens_list and settings_* need an API token with the matching rights — otherwise the panel answers Forbidden.

🔧 Что изменилось по сравнению с upstream

• Numeric user ids везде; users_get_by_telegram_id / _by_email / _by_tag / _by_subscription_id и subscriptions_get_by_uuid удалены (эти маршруты больше не существуют).

• contractTool() — инструменты записи регистрируются с помощью RequestSchema.shape из контракта. Раньше:20 из 23 писатий инструментов записи предоставляли подмножество полей, а MCP SDK молча отбрасывал остальные.

• "users_*остаются написанными вручную: установленный контракт по-прежнему объявляетuuid` для пользователей.

• Новое users_extend_expiration, users_accessible_nodes, subscriptions_get_by_user_id, subscription_templates_list / get / update; config_profiles_update принимает config.

• Клиент: полные тела ошибок API, пустые 2xx-тела при масловых операциях обрабатываются, вручную построенные устойчные к завершаюшему слэшу пути для маршрутов, доступных только в 3.x.

• Начисления из конtarакта (RESET_PERIODS incl. MONTH_ROLLING, USERS_STATUS).

• Поиск конфигурации по нескольким панеллям; readonly рекомендуется по умолчанию;версия повышена до 2.0.0.

🛠 Development

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

🐳 Docker

docker compose up -d

Смотрите docker-compose.yml and pass the same environment variables.

📄 License

авторское право upstream: source.