mcp-remnawave

面向 Remnawave VPN 面板的 MCP 服务器——已适配 Remnawave 3.x

![Remnawave 3.x](https://img.shields.io/badge/Remnawave-3.x-blue

English · Русский

使 MCP 客户端（Claude Code、Claude Code、Clode Code、Cursor 或任何其他客户端）能够通过面板的 REST API 读取和管理用户、节点、主机、配置档案、群组、订阅模板、计费和 HWID 设备。

这是 TrackLine/mcp-remnawave v1.2.0 的维护分支——已对齐 Remnawave 3.x（已在真实运行的 3.3.x 面板上验证），并经过重构，使工具 Schema 从此不会再与面板 API 脱节。

✨ Highlights

Related MCP server: remnawave-mcp-server

Quick start

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 客户端都可以用——把命令指向 节点 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 客户端以项目根目录为 cwd 启动 stdio 服务器，因此只要全局安装一次，生效面板就是你正在工作的那个项目。给某个项目加点面板，只要把 .remnawave.env 拖进该项目即可——服务端侧完全不用动。环境里已存在的变量永远不被覆盖，所以注册客户端时传过来的 env 总是生效。

只读模式

以 REMNAWAVE_READONLY=true 启动。此模式下，写工具（create / update / delete / enable / disable / bulk）完全不会注册，客户端连尝试都不能。当确认需要写入时，把它改为 false 并重启服务。

🧰 工具

约 150 个工具，按面板 API 分组。读工具一直可用；写工具只在关闭只读后提供。

• 按 telegram / email / tag / status 搜索：users_list 传 filters: [{"id": "telegramId", "value": 123456789}]（按需也可加 filterModes、sorting。用这个替代 3.x 中移除的 `by- toda* 路由。

• 话题：users_resolve 只接受 id、shortUuid、username 中 恰好一个。

• 批量工具接收 userIds: number[]（1–500）；users_bulk_update 把变更字段放到 fields 下面。

• users_create 可以传显式的 vlessUuid / ssPassword / trojanPassword / shortUid——服务账号时不显得方便。

| 分组 | 读 | 写 | | ---- | ---- | | 节点 | nodes_list, nodes_get, nodes_tags_list | nodes_create / update / delete, nodes_enable / disable, nodes_restart, nodes_restart_all, nodes_reorder, nodes_reset_raffic, nodes_bulk_* | | 主机 | hosts_list, hosts_get, hosts_tags_list | hosts_create / update / delete, hosts_bulk_* | | 配置档案 | config_profiles_list / get, config_profiles_get_inbounds, config_profiles_get_computed_config, inbounds_list | config_profiles_create / update / delete / reorder |

• config_profiles_update 带 config 时替换的是档案里整个 xray 配置——先读出来、打补丁、再写回去。

• hosts_create 需要传 inbound: { configProfileUuid, configProfileInoundUuid }。

`` api_tokens_list 和 settings_* 需要具有匹配权限的 API 令牌——否则面板会返回 Forbidden。

🔧 与上游相比的变更

• 所有地方均使用数值型用户 ID；移除了 users_get_by_telegram_id / _by_email / _by_tag / _by_subscription_uuid 以及 subscriptions_get_by_uuid（这些路由已不存在）。

• contractTool() ——写入工具根据契约中的 RequestSchema.shape 进行注册。 之前：23 个写入工具中有 20 个只暴露了字段子集，MCP SDK 会静默丢弃其余字段。

• users_* 仍为手写实现：已安装的契约仍为 users 声明了 uuid。

• 新增：users_extend_expiration、users_accessible_nodes、subscriptions_get_by_user_id、 subscription_templates_list / get / update；config_profiles_update 现在接受 profile。

• 客户端：完整的 API 错误体；处理批量操作时的空 2xx 响应体； 针对仅存在于 3.x 的路由采用尾部斜杠安全的手工构建路径。

• 来自契约的枚举（RESET_PERIODS 含 MONTH_ROLLING、USERS_STATUS）。

• 多面板配置查找；默认推荐只读；版本号提升至 2.0.0。

🛠 开发

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

🐳 Docker

docker compose up -d

参见 docker-compose.yml 并传入相同的环境变量。

📄 许可证

MIT。上游作者：TrackLine/mcp-remnawave。