Skip to main content
Glama
remnawave-mcp

remnawave-mcp

by folexz

remnawave-mcp

npm version CI license node

一个用于 Remnawave 面板 API 的 MCP 服务器。

发布在 @folexz 作用域下:npm 上不带作用域的 remnawave-mcp 名称属于另一个不相关的项目,该项目针对 Remnawave 2.7.4,且不适用于 2.8.0+。

npx -y @folexz/remnawave-mcp   # configured via REMNAWAVE_BASE_URL + REMNAWAVE_API_TOKEN_READ/_WRITE

它覆盖了 Remnawave API v3.3.2 的 28 个控制器中的全部 205 个操作——用户、节点、主机、配置档案、小队、订阅、节点插件、基础设施计费、系统统计——这些是从面板自身的 OpenAPI 文档生成的,而非手写。将更新的规范指向 npm run build-spec,工具表面就会随之更新。

亮点

  • 规范驱动,且可自我更新。 npm run update-spec 从 Remnawave 官方发布的副本获取最新的 OpenAPI 文档并重建目录;每个工具的输入模式直接来自操作的参数和请求体。API 的任何部分都不是手写的,重建时会打印一个 diff,列出每个新增、删除或重命名的操作,因此版本升级不会静默丢失工具。

  • 受限的上下文开销。 205 个类型化工具每次请求都会花费约 39k token 的 tools/list。默认配置档只暴露 5 个工具(约 1.4k token),仍然可以触达所有操作——参见为什么不是 205 个工具。

  • 双 token 最小权限认证。 一个读取 token 和一个可选的写入 token。GET 使用读取 token;POST/PATCH/PUT/DELETE 使用写入 token。没有写入 token 时,变更工具根本不会注册——服务器在物理上就是只读的。

  • 为在线面板提供护栏。 变更操作以最小间隔串行化,并在失败时带退避重试,因为每次配置写入都会让面板向所有节点推送配置并重启 Xray。批量操作和删除操作额外要求 confirm: true。

  • 内置字段说明。 下面的注意事项附加在它们影响的操作上,因此会出现在工具描述和 remnawave_describe_operation 输出中。

  • 不会发出注定失败的请求。 16 个端点(auth、passkeys、API token 管理)只对已登录的管理员 JWT 提供服务,并拒绝 API token。它们会从规范中被检测出来,并在本地拒绝并附上说明,而不是发送出去。

  • 逃生通道。 remnawave_request_read / remnawave_request_write 可以触达任何路径,包括未记录的路径和 OpenAPI 无法表达的查询语法。

Related MCP server: mcp-remnawave

要求

  • Node.js ≥ 18

  • 可通过 HTTPS 访问的 Remnawave 面板(3.x)

  • 来自面板的 API token:设置 → API tokens。Remnawave 3.x 支持作用域 token——创建一个带读取作用域的 token,如果需要变更操作,再创建一个带写入作用域的 token。

安装

快捷方式是 npx——参见注册到 Claude Code。要从源码运行:

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

配置

所有配置都是通过 MCP 主机提供的环境变量。不读取任何文件。

变量

必填

默认值

说明

REMNAWAVE_BASE_URL

是

—

面板源地址,例如 https://panel.example.com(不带 /api 后缀)。

REMNAWAVE_API_TOKEN_READ

是

—

读取 token。别名:REMNAWAVE_API_TOKEN,这样面板自己的 .env 名称也能用。

REMNAWAVE_API_TOKEN_WRITE

否

—

写入 token。省略则以只读模式运行。

REMNAWAVE_TOOL_PROFILE

否

minimal

minimal | core | full——要公布多少个类型化工具。

REMNAWAVE_CONTROLLERS

否

—

逗号分隔的控制器 slug;覆盖配置档的类型化工具选择。

REMNAWAVE_MAX_SCHEMA_BYTES

否

2000

超过此大小的输入模式会在 tools/list 中被折叠。

REMNAWAVE_WRITE_MIN_INTERVAL_MS

否

1500

两次变更操作之间的最小间隔。

REMNAWAVE_MAX_RETRIES

否

3

传输失败、429 和 5xx 时的重试次数。

REMNAWAVE_TIMEOUT_MS

否

30000

每次请求的超时时间。

REMNAWAVE_SKIP_CONFIRM

否

0

1 会移除破坏性操作上的 confirm: true 要求。

REMNAWAVE_ALLOW_ADMIN_JWT_OPS

否

0

1 允许 16 个仅限管理员 JWT 的端点(仅当你的 token 确实是管理员 JWT 时设置)。

注册到 Claude Code

只读(推荐默认):

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  -- npx -y @folexz/remnawave-mcp@latest

启用变更操作并为日常控制器提供类型化工具:

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  --env REMNAWAVE_API_TOKEN_WRITE=your_write_token \
  --env REMNAWAVE_TOOL_PROFILE=core \
  -- npx -y @folexz/remnawave-mcp@latest

@latest 让 npx 在每次启动时解析最新发布的版本。要运行本地构建,将命令替换为 node /absolute/path/to/remnawave-mcp/dist/index.js。

注册到 Claude Desktop / 其他 MCP 客户端

{
  "mcpServers": {
    "remnawave": {
      "command": "npx",
      "args": ["-y", "@folexz/remnawave-mcp@latest"],
      "env": {
        "REMNAWAVE_BASE_URL": "https://panel.example.com",
        "REMNAWAVE_API_TOKEN_READ": "your_read_token"
      }
    }
  }
}

为什么不是 205 个工具

tools/list 会在每次请求时重新发送给模型,因此其序列化大小是永久的上下文税。在此规范上实测(npx tsx scripts/tool-stats.ts):

配置档

工具数(读+写)

tools/list

≈ token

工具数(只读)

≈ token

minimal

5

5.6 KB

~1.4k

4

~1.2k

core

91

71 KB

~17.8k

38

~5.9k

full

210

156 KB

~39k

92

~13.9k

Remnawave 的 DTO 是 full 如此昂贵的原因:一个解引用后的 host 对象本身就有约 30 KB 的 JSON Schema,因为它嵌入了所有入站和安全变体。

因此服务器不会在"每个操作一个工具"和"一个笨拙的分发器"之间做选择——它两者都提供,让配置档决定公布多少:

  1. 目录工具(始终开启,3 个工具)。 remnawave_list_operations 浏览和搜索目录,每个操作返回一行紧凑信息;remnawave_describe_operation 返回一个操作的完整 JSON Schema 和字段说明;remnawave_call 按名称执行 205 个操作中的任意一个。通常的循环是 list → describe → call,无论 API 变得多大,成本都保持相同的 1.4k token。这与代理框架延迟加载工具模式时使用的懒加载思路相同。

  2. 类型化工具(按配置档选择)。 为你实际使用的控制器中的每个操作生成一个工具——core 覆盖用户、节点、主机、配置档案、内部小队、系统以及两个批量操作控制器;full 覆盖所有内容;minimal 不覆盖任何内容。超过 REMNAWAVE_MAX_SCHEMA_BYTES 的模式保留顶层字段并丢弃嵌套,同时提供指向 remnawave_describe_operation 的指针以获取完整版本。

  3. 逃生通道(2 个工具)。 用于规范遗漏的任何内容的原始 GET 和原始写入。

每条路由都经过同一个执行器,因此无论使用哪个表面,写入门控、破坏性确认门控、路径模板和查询处理的行为都完全一致。

按口味选择配置档:如果连接了很多 MCP 服务器,选 minimal;如果希望日常操作一步到位,选 core;如果上下文不是问题,选 full。

字段说明——规范未记录的行为

以下所有内容都是针对在线 3.3.2 面板实测得到的,并附加在工具描述中受影响的操作上。

  • PATCH /api/config-profiles 是替换,不是补丁。 请求体是 {uuid, config},config 必须是完整、有效的 Xray 配置。片段会失败并返回 A061: Config doesn't have inbounds。正确的顺序:GET /api/config-profiles/{uuid} → 就地编辑返回的 config 对象 → 将整个对象 PATCH 回去。

  • 面板不会在 127.0.0.1:3000 上应答, 即使在面板主机本身上也是如此,即使 docker-proxy 正在那里监听(curl 返回退出码 52,空回复)。始终使用带 Bearer token 的公共 HTTPS 源地址。

  • 每个响应都包裹在 {"response": ...} 中。 此服务器会解包它,因此工具输出就是载荷本身。

  • 主机通过嵌套的 inbound.configProfileUuid 绑定到配置档案(以及 inbound.configProfileInboundUuid),不是 顶层的 configProfileUuid。已针对在线主机验证:嵌套存在,顶层不存在。

  • 连续执行 PATCH 会导致面板宕机。 每次配置写入都会推送到每个节点并重启那里的 Xray;连续几次后,面板自身的 TLS 监听器就会停止应答。客户端会串行化变更操作(REMNAWAVE_WRITE_MIN_INTERVAL_MS,默认 1500 毫秒),并在传输失败时以指数退避和抖动重试。不要通过并行触发批量更新来绕过它。

  • POST /api/subscription-templates 只创建空模板。 内容由单独的 PATCH /api/subscription-templates 上传。JSON 和 YAML 请求体不能在同一次调用中更新。

  • 主机上的 serverDescription 上限为 30 个字符(由规范中的 maxLength 确认)。它也是让 Hysteria2 主机在 Happ 中正确渲染而不是显示原始 JSON 的原因。

  • 十六个端点仅限管理员 JWT——整个 auth 和 passkeys 控制器,以及 API token 管理(GET/POST /api/tokens、DELETE /api/tokens/{uuid}、GET /api/tokens/scopes)。面板在这些端点上对 API token 返回 401/403。此服务器会从规范中检测它们并在本地拒绝;如果你配置的 token 确实是管理员 JWT,REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1 会解除门控。

  • GET /api/users/stream 以换行分隔的 JSON 应答,而不是单个文档。它会被解析为用户记录数组,而不是作为文本块返回。

  • PATCH /api/hosts 确实 是真正的部分补丁——仅 {uuid, serverDescription} 就能工作。只有配置档案具有整体替换的语义。已在线验证。

  • 错误以 {message, errorCode} 的形式返回;errorCode(例如 A061)会包含在此服务器的错误文本中。

工具覆盖

每个控制器都可以通过 remnawave_call 和逃生通道触达。类型化列显示哪些控制器在 REMNAWAVE_TOOL_PROFILE=core 下获得单独的工具。

Controller slug

操作数

在 core 下类型化

users

17

是

node-plugins

18

—

nodes

15

是

infra-billing

12

—

internal-squads

12

是

system

12

是

users-bulk-actions

10

是

config-profiles

9

是

external-squads

8

—

auth

7

—

bandwidth-stats

7

—

connections

7

—

hosts

7

是

hwid-user-devices

7

—

subscription-page-configs

7

—

subscriptions

7

—

subscription-template

6

—

node-integrations

5

—

passkeys

5

—

snippets

5

—

api-tokens

4

—

hosts-bulk-actions

4

是

metadata

4

—

public-subscription

3

—

remnawave-settings

2

—

subscription-request-history

2

—

subscription-settings

2

—

keygen

1

—

总计

205

针对在线服务器运行 remnawave_list_operations 以获取精确、当前的集合。

示例

无需任何类型化工具即可浏览和调用:

// 1. What is there?
{ "tool": "remnawave_list_operations", "arguments": { "controller": "nodes" } }

// 2. What does it take?
{ "tool": "remnawave_describe_operation",
  "arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart" } }

// 3. Do it.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart",
                 "params": { "uuid": "…" } } }

params、body 和 query 也可能以 JSON 文本形式到达——"params": "{\"uuid\":\"…\"}"——因为某些 MCP 客户端会原样转发未类型化的工具参数,而不是解析它们。该字符串会为您解析;非 JSON 的字符串会被拒绝,并附上说明消息。

安全地编辑配置档案(A061 陷阱):

// Read the whole profile first — PATCH replaces the config wholesale.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_get_config_profiles_uuid", "params": { "uuid": "…" } } }

// Send the full, edited config back.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_patch_config_profiles",
                 "params": { "body": { "uuid": "…", "config": { /* complete Xray config */ } } } } }

规范无法表达的查询语法:

{ "tool": "remnawave_request_read",
  "arguments": { "path": "/api/users",
                 "query": { "size": 25, "start": 0,
                            "filters[0][id]": "status", "filters[0][value]": "ACTIVE" } } }

测试

npm run build
npm test            # 50 unit tests + the offline smoke suite
npm run test:unit   # unit tests alone

单元测试覆盖了那些会静默失败的环节:通过 Remnawave 的递归 DTO 进行 $ref 展开、工具名称推导(长度预算、确定性、冲突检测)、目录差异、两个写入门控、admin-JWT 门控、模式折叠和 NDJSON 解析。

针对真实面板的只读检查

在面板可达且环境中存在只读令牌的情况下,冒烟脚本还会执行实时的只读调用(绝不执行变更操作):

REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$REMNAWAVE_API_TOKEN" \
npm run smoke

在令牌已存在的位置(例如面板主机上)运行它,这样机密就不会传输。脚本打印的是形状——类型、键名、数组长度——而绝不打印载荷值,因此其输出可以安全地粘贴到 issue 中。

护栏检查特意指向 http://127.0.0.1:9,因此任何曾经失效开放的门控都无法触达真实面板。

验证写入路径

读取操作无法证明令牌路由、节流、确认门控和部分补丁语义确实有效。scripts/write-check.mjs 在无人关联的对象上证明这些行为,并恢复它触碰的一个预先存在的对象:

REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$T" REMNAWAVE_API_TOKEN_WRITE="$T" \
node scripts/write-check.mjs --i-understand-this-mutates [--host-uuid <uuid>]

它会创建一个没有入站和成员的内部小队,然后将其删除,接着重写一台主机上的 serverDescription 并恢复原始值。没有确认标志时它拒绝启动,如果留下任何残留则报告非零退出码。

针对在线 3.3.2 面板,它确认了:确认门控在真实的 DELETE 上生效;部分 PATCH /api/hosts 有效;面板拒绝 31 个字符的 serverDescription;原始值(包括 null)能够往返;连续变更操作在配置的 1500 毫秒下限下间隔 1525 和 1524 毫秒。

本地检查

REMNAWAVE_BASE_URL=https://panel.example.com REMNAWAVE_API_TOKEN_READ=xxx npm run inspect

更新 API 规范

关于 API 的一切都来自一个文件,因此跟踪新的 Remnawave 版本只需一条命令:

npm run update-spec            # fetch the newest spec + rebuild the catalogue
npm run update-spec -- --strict  # additionally fail if any operation disappeared or was renamed
npm run build && npm test      # compile and verify

规范的来源

https://cdn.remna.st/docs/openapi.json——由 Remnawave 自己的 Build&Push OpenAPI Specs 工作流在每个上游标签上发布,因此它始终描述最新版本。可通过 --url <u> 或 REMNAWAVE_SPEC_URL 覆盖以固定不同的来源。

面板实例不是可用的来源:除非部署启用了文档,否则文档被禁用;即使启用,Swagger 也挂载在 /backend-tools/swagger 下,而通常的反向代理不会路由该路径。探测在线 3.3.2 面板时,所有常规规范路径均返回 404。

下载只有在解析为具有非空 paths 的 OpenAPI 文档后才会写入磁盘,因此错误页面或强制门户无法破坏可用的规范。

之后要检查什么

build-spec 将新目录与之前的目录进行差异比较,并打印所有更改:

build-spec: Remnawave API v3.4.0 -> 211 operations, 28 controllers, 315 KB
  methods: DELETE=22 GET=90 PATCH=19 POST=78 PUT=2  admin-JWT-only: 16
  diff: API version 3.3.2 -> 3.4.0
  REMOVED — tools that will disappear (1):
    remnawave_get_old_thing  (GET /api/old-thing)
  added (7):
    ...
  • REMOVED / RENAMED 对任何在提示词或脚本中引用这些工具的人来说都是破坏性的。 --strict 将其变为非零退出码,这是自动化应使用的标志。

  • added 是安全的;新操作可通过 remnawave_call 立即访问,如果其控制器在活动配置文件中, 则会获得类型化工具。

  • schema changed 值得对您实际使用的操作进行一瞥。

npm test 随后重新检查磁盘上的目录是否与全新构建匹配、所有工具名称是否唯一且在 64 字符预算内,以及护栏是否仍然有效。

自动化

npm run update-spec -- --strict   # exits non-zero on a breaking catalogue change
npm test
npm version minor --no-git-tag-version
git commit -am "chore: Remnawave API 3.4.0" && git push
git tag "v$(node -p "require('./package.json').version")" && git push --tags

推送的标签触发发布工作流,该工作流重新发布到 npm。注册了 @folexz/remnawave-mcp@latest 的客户端将在下次启动时获取新版本。

发布(维护者)

首次发布——必须手动

npm 无法为尚不存在的包配置受信任的发布者:该设置位于包自身的设置页面上。这是一个已知且仍未解决的限制(npm/cli#8544),并且同样适用于作用域包。因此版本 0.1.0 必须从已登录的机器上发布:

npm whoami            # must print the account that owns the @folexz scope
npm publish --access public

--access public 是必需的:作用域包默认为受限。

然后切换到无令牌发布

包存在后,在 npmjs.com → @folexz/remnawave-mcp → Settings → Trusted Publisher 中添加一个 GitHub Actions 发布者,仓库为 folexz/remnawave-mcp,工作流为 release.yml。package.json 中的 repository.url 必须与 GitHub 仓库完全匹配——它确实匹配。

之后,.github/workflows/release.yml 会在任何推送的 vX.Y.Z 标签上通过 OIDC 发布——无需令牌、无需机密,并自动附加来源证明:

npm version patch --no-git-tag-version
git commit -am "chore: v0.1.1"
git push
git tag v0.1.1 && git push origin v0.1.1

该工作流从锁文件重新安装、重新构建、运行单元测试和离线冒烟套件,如果标签与 package.json 不匹配则快速失败。

注册了 @folexz/remnawave-mcp@latest 的客户端将在下次启动时获取新版本。

安全说明

  • 令牌仅从环境变量读取,绝不记录。日志输出到 stderr;stdout 是 MCP JSON-RPC 通道。

  • 建议仅配置 REMNAWAVE_API_TOKEN_READ。没有写入令牌,变更工具就不存在,因此被攻破或混淆的客户端无法更改面板。

  • 订阅端点返回可用的客户端配置。请将其输出视为机密。

  • 切勿提交真实令牌。.env 已被 gitignore;.env.example 展示了其形状。

已知限制

  • 请求体验证委托给面板。 此服务器仅检查必需的参数和必需的 body 是否存在;它不会根据模式验证请求体的内部形状。这是有意为之——面板已经验证了每个字段,并以精确的 message + errorCode(例如 A061)响应,在本地重复这一工作意味着要附带一个 JSON Schema 验证器以及一份必然漂移的规则副本。代价是格式错误的请求体需要一次往返才能发现。

  • 逃生舱口绕过每个操作的门控。 remnawave_request_write 按设计是原始的:它仍然需要写入令牌,仍然经过节流和重试逻辑,但它不应用破坏性的 confirm 门控或 admin-JWT 检查,因为它没有操作可供查找。除非您需要规范未描述的路由,否则请优先使用 remnawave_call。

  • 工具仅与随附的规范(v3.3.2)一样新。 不同次要版本的面板可能暴露规范未描述的路由;这就是逃生舱口的用途。参见 更新 API 规范。

  • Admin-JWT 端点被门控,而非实现。 此服务器携带 API 令牌;它不执行管理员登录、不持有会话、也不刷新 JWT。如果您以管理员 JWT 作为令牌并提供 REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1,这 16 个端点将变为可调用,但过期和续期是您的问题。

  • Prometheus basic-auth 指标端点不属于此规范,也未暴露。

  • write-check.mjs 会执行变更操作。 它是维护者工具,已从 npm test 中排除,并且在没有明确确认标志时拒绝运行。

许可证

MIT — 参见 LICENSE。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Enables MCP clients like Claude Code, Claude Desktop, or Cursor to read and manage Remnawave 3.x VPN panel resources — users, nodes, hosts, config profiles, squads, subscription templates, billing, and HWID devices — through the panel's REST API, with contract-driven tool schemas, numeric user IDs, multi-panel config lookup, and an optional readonly mode.
      204
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables managing and observing Technitium DNS Server through MCP, including read-only or read-write tool surfaces, scoped bearer authentication, audit logging, and confirmation gates for destructive operations.
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables managing a Remnawave VPN panel from MCP clients, providing tools for users, nodes, subscriptions, statistics, billing, and system operations, plus resources and prompts for common admin tasks.
      190
      MIT