remnawave-mcp
remnawave-mcp
一个用于 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 主机提供的环境变量。不读取任何文件。
变量 | 必填 | 默认值 | 说明 |
| 是 | — | 面板源地址,例如 |
| 是 | — | 读取 token。别名: |
| 否 | — | 写入 token。省略则以只读模式运行。 |
| 否 |
|
|
| 否 | — | 逗号分隔的控制器 slug;覆盖配置档的类型化工具选择。 |
| 否 |
| 超过此大小的输入模式会在 |
| 否 |
| 两次变更操作之间的最小间隔。 |
| 否 |
| 传输失败、429 和 5xx 时的重试次数。 |
| 否 |
| 每次请求的超时时间。 |
| 否 |
|
|
| 否 |
|
|
注册到 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):
配置档 | 工具数(读+写) |
| ≈ token | 工具数(只读) | ≈ token |
| 5 | 5.6 KB | ~1.4k | 4 | ~1.2k |
| 91 | 71 KB | ~17.8k | 38 | ~5.9k |
| 210 | 156 KB | ~39k | 92 | ~13.9k |
Remnawave 的 DTO 是 full 如此昂贵的原因:一个解引用后的 host 对象本身就有约 30 KB 的 JSON Schema,因为它嵌入了所有入站和安全变体。
因此服务器不会在"每个操作一个工具"和"一个笨拙的分发器"之间做选择——它两者都提供,让配置档决定公布多少:
目录工具(始终开启,3 个工具)。
remnawave_list_operations浏览和搜索目录,每个操作返回一行紧凑信息;remnawave_describe_operation返回一个操作的完整 JSON Schema 和字段说明;remnawave_call按名称执行 205 个操作中的任意一个。通常的循环是 list → describe → call,无论 API 变得多大,成本都保持相同的 1.4k token。这与代理框架延迟加载工具模式时使用的懒加载思路相同。类型化工具(按配置档选择)。 为你实际使用的控制器中的每个操作生成一个工具——
core覆盖用户、节点、主机、配置档案、内部小队、系统以及两个批量操作控制器;full覆盖所有内容;minimal不覆盖任何内容。超过REMNAWAVE_MAX_SCHEMA_BYTES的模式保留顶层字段并丢弃嵌套,同时提供指向remnawave_describe_operation的指针以获取完整版本。逃生通道(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 | 操作数 | 在 |
| 17 | 是 |
| 18 | — |
| 15 | 是 |
| 12 | — |
| 12 | 是 |
| 12 | 是 |
| 10 | 是 |
| 9 | 是 |
| 8 | — |
| 7 | — |
| 7 | — |
| 7 | — |
| 7 | 是 |
| 7 | — |
| 7 | — |
| 7 | — |
| 6 | — |
| 5 | — |
| 5 | — |
| 5 | — |
| 4 | — |
| 4 | 是 |
| 4 | — |
| 3 | — |
| 2 | — |
| 2 | — |
| 2 | — |
| 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
EU cloud as MCP tools: VPS, databases, caches, storage, containers and more. Takes an API token.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
Access Siglume API Store tools and external MCP Router servers.
Related MCP Servers
- AlicenseCqualityBmaintenanceWraps the Remnawave API to provide per-operation MCP tools with mutation safety and data redaction, enabling secure interaction with Remnawave panel.100MIT
- AlicenseCqualityBmaintenanceEnables 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.204MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseCqualityCmaintenanceEnables 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.190MIT