Victron Vrm Mcp — Mcp Server

Victron VRM MCP — MCP 服务

适用于 Victron Energy VRM 云 API 的 MCP 服务。通过 Streamable HTTP 提供 53 个 VRM 工具，可直接用于 Anthropic MCP Connector API 和任何支持 HTTP 的 MCP 客户端。

53 个工具 | Streamable HTTP | 安全优先 | 506 项测试（415 项离线测试 + 91 项在线测试）| 兼容 MCP Connector

---

我应该选择哪个软件包？

这是两个软件包中云端／远程的一款。本地／局域网版本是 victron-tcp。

	victron-tcp	victron-vrm-mcp（本仓库）
传输方式	stdio（本地子进程）	Streamable HTTP（远程）
数据来源	局域网上的 Modbus TCP + MQTT	VRM 云 API
需要访问局域网上的 GX	是	否
不在船上／房子里时能否使用	否	是
互联网中断时能否使用	是	否
延迟	实时（约 50 ms）	约 15 分钟（VRM 采样间隔）
原始寄存器访问	是（900 多个寄存器）	否
写入支持	目前只读；计划通过 MQTT 支持写入	24 个破坏性操作工具，全部需通过 confirm 确认
兼容 MCP Connector API	否（stdio）	是（HTTPS）
客户端	Claude Code、Claude Desktop、Cursor、Windsurf	Anthropic Messages API，以及任何支持通过 HTTP 使用 MCP 的客户端
身份验证	本地无身份验证（信任局域网）	每次请求使用 VRM 个人访问令牌

**在以下情况下使用 victron-tcp：**你和 GX 设备处于同一局域网，并且需要实时访问和原始寄存器支持。 **在以下情况下使用 victron-vrm-mcp：**你需要远程访问、要通过 MCP Connector 构建由 API 提供支持的应用，或不想向局域网外部开放任何服务。

你可以同时使用两者——它们适用于不同场景。

---

安装

与 victron-tcp 不同，此软件包是一个由你自行托管的服务，而不是由客户端启动的进程。启动一次服务，在前面配置 HTTPS，然后让 MCP 客户端连接到它的 URL。

从 npm 运行（推荐）

# one-off (no install)
npx victron-vrm-mcp

# or install globally
npm install -g victron-vrm-mcp
victron-vrm-mcp

# or pin in a project
npm install victron-vrm-mcp
npx victron-vrm-mcp

默认监听 http://127.0.0.1:3000/mcp。使用环境变量（PORT、HOST、ALLOWED_ORIGINS、VRM_ALLOWED_SITES、VRM_AUTH_SCHEME）进行配置——参见 .env.example。

从源代码运行（开发）

git clone https://github.com/lubosstrejcek/victron-vrm-mcp.git
cd victron-vrm-mcp
npm install
npm run build
npm start

默认绑定地址相同（http://127.0.0.1:3000/mcp）。

Docker

Dockerfile 已列入计划。目前，你可以按需调整以下最简单行命令：

docker run --rm -it -p 3000:3000 -e HOST=0.0.0.0 \
  -e ALLOWED_ORIGINS="https://claude.ai" \
  node:22-alpine sh -c "npx -y victron-vrm-mcp"

公共 HTTPS（推荐）

远程客户端需要真正的 TLS。无需开放防火墙端口的最简单方式是：Cloudflare Tunnel。

cloudflared tunnel create vrm
cloudflared tunnel route dns vrm victron-vrm.example.com
cloudflared tunnel run --url http://127.0.0.1:3000 vrm

现在，https://victron-vrm.example.com/mcp 可通过有效证书访问，且无需开放端口。其他方案：nginx/Caddy 反向代理、Fly.io、Cloudflare Workers 适配器（计划中）。

Anthropic Messages API（MCP Connector）

{
  "mcp_servers": [{
    "type": "url",
    "url": "https://victron-vrm.example.com/mcp",
    "name": "victron-vrm",
    "authorization_token": "<your-vrm-personal-access-token>"
  }],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "victron-vrm" }]
}

Claude Code / Cursor / Windsurf（HTTP 传输）

claude mcp add-json victron-vrm '{"type":"http","url":"https://victron-vrm.example.com/mcp","headers":{"Authorization":"Bearer YOUR_VRM_TOKEN"}}'

不知道 VRM 令牌？

在 VRM → Preferences → Integrations → Access tokens 创建个人访问令牌（端点：POST /users/{idUser}/accesstokens/create）。访问令牌长期有效、可撤销，并且是今后受支持的第三方身份验证方式。

⚠️ VRM Bearer 令牌（/auth/login、/auth/loginAsDemo）自 2026-06-01 起已弃用（现已列入官方 OpenAPI 规范）。此服务仍支持通过 x-vrm-auth-scheme: Bearer 使用它们进行测试，但新集成必须使用访问令牌。每当使用 Bearer 方案时，系统都会记录警告。

在获取访问令牌前进行快速冒烟测试时，GET https://vrmapi.victronenergy.com/v2/auth/loginAsDemo 会针对 Victron 演示租户返回一个短期有效的 Bearer 令牌。

不知道 idSite？

先调用 vrm_list_installations——它会返回令牌可访问的所有站点。如果你有 12 个字符的门户 ID，也可以调用 vrm_get_site_id 进行解析。

要求

• Node.js 22.11+（支持的两个 LTS 版本线：22 和 24）
• VRM 个人访问令牌（或用于测试的演示登录 Bearer）
• 如果希望 MCP Connector API 能够访问，则需要公共 HTTPS

---

工具

53 个工具涵盖 88+ 项 VRM 操作（53 项直接操作 + 通过通用 vrm_widget 分发器支持的 35+ 个 widget 端点）。所有破坏性工具都受 confirm: true 控制；每个工具都声明了 inputSchema、outputSchema 和 MCP 注释。

发现与查找（4 个工具）

工具	描述
vrm_list_installations	列出令牌可访问的所有站点（支持使用 limit 截断 Markdown 内容）
vrm_search_sites	按站点 ID、电子邮件、用户名、序列号、站点标识符或电子邮件域名搜索
vrm_get_site_id	将 12 位门户 ID 解析为数字 idSite
vrm_list_invites	列出用户发出和收到的邀请

监控 — 读取（11 个工具）

工具	描述
vrm_get_system_overview	站点已连接的设备及其角色
vrm_get_diagnostics	每台设备最近记录的属性值
vrm_get_stats	时间序列统计数据（15 分钟/小时/天/周/月/年）
vrm_get_overallstats	生命周期汇总统计数据
vrm_get_alarms	已配置的告警、设备、通知用户和可用属性
vrm_get_site_users	站点上的用户、邀请、访问请求和群组链接
vrm_get_tags	按来源（用户/团队/群组/预定义）分组的标签
vrm_get_dynamic_ess_settings	当前 Dynamic ESS 配置
vrm_get_gps_download	GPS 位置历史记录
vrm_get_forecasts_last_reset	上次重置预测的时间戳（从未重置则为 0）
vrm_get_custom_widgets	站点上配置的自定义 widget

Widgets（3 个工具 — 涵盖 35+ 个 widget 端点）

工具	描述
vrm_widget	任意 VRM widget 名称的通用分发器（BatterySummary、SolarChargerSummary、TankSummary、VeBusState、MPPTState、InputState、InverterState、PVInverterStatus、MotorSummary、GlobalLinkSummary、MeteorologicalSensorOverview、Status、HoursOfAc、LithiumBMS、DCMeter、FuelCellState、BatteryRelayState、ChargerRelayState、GatewayRelayState、SolarChargerRelayState、BatteryMonitorWarningsAndAlarms、VeBusWarningsAndAlarms、InverterChargerState、InverterChargerWarningsAndAlarms、EssBatteryLifeState、IOExtenderInOut、BMSDiagnostics、HistoricData、TempSummaryAndGraph、TempAirQuality、EvChargerSummary 等）
vrm_widget_graph	时间序列图表，支持 attributeCodes[] / attributeIds[]、start/end、useMinMax
vrm_widget_generator_state	发电机状态变化时间线

写入 — 低风险（4 个工具，需确认）

工具	描述
vrm_set_favorite	将站点标记为收藏或取消收藏
vrm_tags_add	为站点添加标签
vrm_tags_remove	移除站点上的标签
vrm_clear_alarm	确认活动告警

写入 — 中风险（5 个工具，需确认）

工具	描述
vrm_add_alarm	创建告警（浮点数或枚举阈值类型）
vrm_edit_alarm	修改现有告警
vrm_delete_alarm	删除告警定义
vrm_reset_forecasts	重置站点的预测基准
vrm_set_site_settings	更新站点名称/备注/地理围栏/告警监控/Node-RED 限制等

写入 — 高影响（1 个工具，需确认）

工具	描述
vrm_set_dynamic_ess_settings	写入 Dynamic ESS 配置（计划、b2g、priceSchedule、batteryKwh 等）

访问管理（8 个工具，需确认）

工具	说明
vrm_invite_user	通过电子邮件邀请用户，并设置访问级别（0=监控，1=管理员，2=技术人员）
vrm_unlink_user	从站点移除用户
vrm_unlink_installation	将当前用户从站点移除（自行解除关联）
vrm_set_user_rights	批量更新各用户的访问级别
vrm_set_invite_rights	批量更新待处理邀请的访问级别
vrm_link_user_groups	关联用户组并设置访问级别
vrm_set_user_group_access_level	更改或移除用户组的访问级别
vrm_add_site	将一个安装添加到用户帐户

访问令牌（2 个工具，需确认）

工具	说明
vrm_create_access_token	创建长期个人访问令牌
vrm_delete_access_token	按 ID 撤销一个令牌，或使用 "*" 撤销所有令牌——可能导致自己被锁定在外

身份验证（3 个工具——Bearer 流程，已于 2026-06-01 弃用）

工具	说明
vrm_auth_login_as_demo	获取演示租户的短期 Bearer（只读）
vrm_auth_login	使用电子邮件和密码登录（已弃用，存在安全风险——请使用访问令牌）
vrm_auth_logout	使当前 Bearer 会话失效

自定义小组件 CRUD（4 个工具）

工具	说明
vrm_get_custom_widgets	列出站点上的自定义小组件
vrm_create_custom_widget	创建（需确认）
vrm_patch_custom_widget	更新（需确认）
vrm_delete_custom_widget	删除（需确认）

数据属性（2 个工具）

工具	说明
vrm_find_by_data_attributes	根据属性条件搜索用户的安装（bs>=50,au=(1,2)）；服务端通过 page/count 分页
vrm_list_data_attributes	所有 VRM 属性定义目录

管理员 / 集合（6 个工具——大多数需要管理员权限）

工具	说明
vrm_admin_list_devices	系统中的所有设备
vrm_admin_data_attributes_count	按数据属性条件统计安装数量
vrm_admin_search_download	批量搜索导出
vrm_list_firmwares	固件目录（需要 feedChannel 和 victronConnectVersion）
vrm_add_system	注册新系统（需确认）
vrm_installation_overview_download	批量概览导出（以 base64 返回二进制载荷）

资源

URI	内容
docs/vrm-api-openapi.yaml	内置的 VRM OpenAPI 3.1 规范（78 个端点，更新于 2026-04），供参考

---

配置

环境变量

变量	默认值	说明
PORT	3000	HTTP 端口
HOST	127.0.0.1	绑定地址
MCP_PATH	/mcp	端点路径
VRM_AUTH_SCHEME	Token	转发到 VRM 时使用的默认方案。使用 Token（访问令牌）。VRM 已于 2026-06-01 弃用 Bearer。每个请求可通过 x-vrm-auth-scheme 标头覆盖。
VRM_ALLOWED_SITES	（未设置）	以逗号分隔的 idSite 允许列表。若未设置，则允许访问令牌可访问的任何站点。
ALLOWED_ORIGINS	（未设置）	以逗号分隔的允许 Origin 标头值列表。若未设置，则仅接受同源请求和回环地址。

本地 .env（可选）

将 .env.example 复制为 .env 并进行调整。Node 20.6+ 可直接加载：

node --env-file=.env dist/index.js

.env 已加入 gitignore。VRM 令牌绝不能放入 .env——应在每个请求的 Authorization 标头中传递。

单请求标头

标头	用途
Authorization: Bearer <vrm-token>	必需。 要转发的 VRM 令牌。
x-vrm-auth-scheme: Token|Bearer	可选。覆盖本次请求的 VRM_AUTH_SCHEME。/auth/loginAsDemo 令牌请使用 Bearer。
x-vrm-skip-confirms: 1	可选。绕过破坏性工具的 confirm: true 门槛。仅用于自动化 — 绝不可用于交互式会话。会记录为 skip_confirms_enabled 警告。
Origin	根据 ALLOWED_ORIGINS（或同源）进行验证，以防御 DNS 重绑定。
mcp-protocol-version	根据支持的版本（2025-06-18、2025-03-26）进行验证。

---

安全模型

层	功能
Origin 标头验证	除非 Origin 位于 ALLOWED_ORIGINS 中（或在本地开发时与主机匹配），否则拒绝跨源请求。用于防御 DNS 重绑定。
严格的 Accept + Content-Type	POST 必须发送 Content-Type: application/json，且 Accept 必须同时包含 application/json 和 text/event-stream。同时防范简单 POST CSRF。
MCP-Protocol-Version 白名单	仅接受此服务支持的版本；未知版本 → 400。
必须提供 Bearer 令牌	在调用 VRM 之前拒绝缺失或长度明显过短的令牌。
令牌绝不存储 / 绝不记录	令牌仅存在于转发令牌的 fetch 调用中。记录器会自动剥除任何包含 token 或 authorization 的键。
Zod 输入验证	对每个工具参数进行架构验证。idSite/idUser 必须为正整数；小组件名称必须匹配严格的 PascalCase 正则表达式；请求正文按工具进行架构验证。
安全的 URL 路径构造	路径参数通过共享的 sitePath() / userPath() 助手中的 encodeURIComponent 进行 URL 编码。不会将字符串模板插入 URL。
VRM 基础 URL 主机锁定	客户端拒绝调用除 HTTPS 上的 vrmapi.victronenergy.com 之外的任何地址。
破坏性操作门控	写入/删除工具要求 { confirm: true }，或要求提供 x-vrm-skip-confirms: 1 标头（自动化选择启用）。拒绝操作由服务端执行，而非仅由 MCP 客户端执行。设置 MCP 注解（destructiveHint、idempotentHint、readOnlyHint），以便客户端强制执行用户体验确认。
可选站点允许列表	VRM_ALLOWED_SITES=123,456 会将服务限制在固定站点集合中。在访问 VRM 前拒绝不符合条件的请求。
速率限制感知	429 响应会显示 Retry-After。不会静默重试。
错误正文脱敏	VRM 错误正文会缩减为 error_code: errors-text，并截断至 256 个字符。原始响应正文绝不会传递给客户端。
每个请求均无状态	每个请求都会创建全新的 McpServer + StreamableHTTPServerTransport — 不共享跨请求状态，也不进行会话认证。
结构化 JSON stderr 日志	所有运行事件均记录为单行 JSON；剥除令牌/授权相关键。
DELETE 返回 405	服务为无状态；没有可删除的会话。

---

工作原理

┌──────────────────────────┐       HTTPS + Bearer token        ┌──────────────────────┐
│  MCP client              │ ────────────────────────────────▶ │  victron-vrm-mcp     │
│  (Connector API, Claude  │                                    │  (Streamable HTTP)   │
│   Code, Cursor, etc.)    │                                    └──────────┬───────────┘
└──────────────────────────┘                                               │
                                                                           │ x-authorization: Token …
                                                                           ▼
                                                        https://vrmapi.victronenergy.com/v2

该服务是无状态的 — 每个 MCP 请求都携带自己的 VRM 令牌。每个请求都会构建全新的 McpServer + StreamableHTTPServerTransport，并通过 SDK 的 RequestHandlerExtra.authInfo 通道转发身份验证信息。

---

调试

MCP Inspector 是以交互方式试用该服务最快捷的方法。

# Terminal 1 — start the server
npm run build && npm start
# (or: PORT=3000 npx victron-vrm-mcp)

# Terminal 2 — launch the Inspector UI
npm run inspect
# Then in the UI:
#   Transport:  Streamable HTTP
#   URL:        http://127.0.0.1:3000/mcp
#   Headers:    Authorization: Bearer <your-vrm-token>
#               x-vrm-auth-scheme: Token   (or Bearer for /auth/loginAsDemo tokens)

日志以单行 JSON 格式写入 stderr（Streamable HTTP 传输不会将 stderr 捕获并传递给客户端 — 请参阅规范中的调试指南）。对于客户端可见的诊断信息，规范提供了 notifications/message（计划在未来版本中推出）。

测试

16 个文件中共有 415 项测试，运行时间约 12 秒——完全离线，不会调用 VRM 网络：

npm test           # build + the offline suite
npm run test:unit  # unit tests only (no server spawn)
npm run test:live  # 91 extra tests against VRM's public demo tenant (needs network)

tests/live.test.ts 被有意排除在 vitest.config.ts 之外，只通过自己的 vitest.live.config.ts 运行，因此 npm test 和 CI 不会依赖 vrmapi.victronenergy.com 是否在线。无需凭据——它会自行申请匿名演示令牌。

文件	覆盖范围
tests/handlers.test.ts	在进程内针对桩接 VRM 执行每个工具处理程序：请求构造（方法／路径／查询／正文）、Markdown + structuredContent 格式处理、在 VRM 边界验证破坏性操作门控、错误信息脱敏、VRM_ALLOWED_SITES 强制执行
tests/helpers.test.ts	zod 模式、sitePath／userPath 编码、requireConfirm + skip 绕过、resolveAuth 令牌校验、formatVrmError 脱敏
tests/client.test.ts	令牌长度校验、方案转发、数组查询编码、主机固定、4xx → VrmApiError、429 Retry-After、二进制下载往返
tests/logger.test.ts	自动脱敏 token／authorization 键（不区分大小写）
tests/http.test.ts	端到端 HTTP：404/405/401/403/406/415/400/200、Origin 验证、确认门控、skip 标头
tests/tools.coverage.test.ts	验证全部 53 个工具的形状和注释正确；每个破坏性工具在未确认时都会拒绝执行，并在使用 skip 标头时通过
tests/outputSchema.test.ts	每个工具都声明至少包含 1 个属性的 outputSchema；描述规范检查（长度、提及端点、不含注入标记、破坏性工具说明风险）
tests/regressions.test.ts	针对特定错误的回归锁定：skip 绕过确认、firmwares 必填参数、二进制下载、拒绝路径遍历、widget 名称正则表达式、限制范围
tests/fuzz.test.ts	格式错误的 JSON、1 MB 正文、Unicode／控制字符／XSS／SQL 注入字符串、数组长度限制、Content-Type 边界情况、令牌泄漏哨兵

CI：.github/workflows/ci.yml 会在 Node 22 / 24（两个受支持的 LTS 版本）上，对每次推送和 PR 运行完整测试套件并检查覆盖率阈值（src/ 中行覆盖率 80%／分支覆盖率 72%），此外还会运行令牌泄漏哨兵 grep 和 npm audit。

评测

evals/*.xml —— 12 项多工具场景评测（不在 CI 中运行，由人工使用 LLM 客户端评分）。涵盖发现 + 概览、电池最近一小时数据、警报分类、按 SOC 查找、邀请用户、轮换访问令牌、标签管理、安全拒绝、站点 ID 查询、每日健康检查、ESS 配置变更、自动化夜间任务。

---

路线图

已交付：

• 53 个工具，涵盖 88+ 项 VRM 操作
• Streamable HTTP 传输 + MCP Connector API 支持
• 安全加固（Origin／Accept／Content-Type／Protocol-Version、令牌脱敏、确认门控、站点允许列表、基 URL 固定）
• 每个工具均提供 outputSchema
• 506 项测试（415 项离线 + 91 项在线）+ Node 22/24 上的 CI
• 12 项场景评测

计划中：

• Cloudflare Workers 适配器（适合无状态部署）
• Docker 镜像
• 与 VRM 的 200 窗口／3 req/s 相匹配的令牌桶限流器
• 录制夹具测试（离线 VRM 响应快照）
• VRM 添加游标式分页后，为 vrm_list_data_attributes 实现分页

---

参考资料

• VRM API 文档
• VRM API 在线文档（试用）
• Anthropic MCP Connector API
• Model Context Protocol 规范
• 与 Victron Energy 产品进行数据通信（白皮书）

许可证

MIT