Mcp Server For Victron Energy Gx Devices

Victron TCP — MCP 服务

将 AI 助手连接到 Victron Energy 系统。从本地网络读取实时太阳能、电池、电网和逆变器数据，无需云服务。

32 个工具 | 23 个提示词 | 2 个资源 | 900+ 个寄存器 | Modbus TCP + MQTT

---

我应该选择哪个软件包？

这是这一对软件包中的本地 / LAN部分。远程 / 云端部分是 victron-vrm-mcp。

	victron-tcp（此代码库）	victron-vrm-mcp
传输方式	stdio（本地子进程）	Streamable HTTP（远程）
数据来源	LAN 上的 Modbus TCP + MQTT	VRM 云 API
需要访问 LAN 上的 GX	是	否
离开船只 / 房屋时是否可用	否	是
互联网中断时是否可用	是	否
延迟	实时（约 50 ms）	约 15 分钟（VRM 采样间隔）
原始寄存器访问	是（900+ 个寄存器）	否
写入覆盖范围（计划中）	广泛——D-Bus 公开的所有内容	窄——仅限 VRM 允许远程操作的内容（Dynamic ESS、清除警报、标签等）
兼容 MCP Connector API	否（stdio）	是（HTTPS）
客户端	Claude Code、Claude Desktop、Cursor、Windsurf	Anthropic Messages API + 任何支持通过 HTTP 使用 MCP 的客户端
身份验证	本地无（信任 LAN）	每次请求均需提供 VRM 个人访问令牌

**以下情况适合使用此软件包：**你与 GX 设备处于同一 LAN，并且需要实时、低延迟读取访问权限和原始寄存器支持。
**以下情况适合使用 victron-vrm-mcp：**你需要远程访问、要通过 MCP Connector 构建由 API 支持的应用，或不想在 LAN 上暴露任何内容。

你可以同时使用两者——它们适用于不同场景，风险特征也各不相同。

---

安装

Claude Code

claude mcp add-json victron-tcp '{"type":"stdio","command":"npx","args":["-y","victron-tcp"]}'

Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "victron-tcp": {
      "command": "npx",
      "args": ["-y", "victron-tcp"],
      "env": {
        "VICTRON_HOST": "192.168.1.50",
        "VICTRON_TRANSPORT": "mqtt",
        "VICTRON_PORTAL_ID": "your-portal-id"
      }
    }
  }
}

不知道设备 IP？

直接询问 AI：

Find my Victron GX device on the network and set it up.

它会扫描你的网络、测试连接，并为你生成配置。

要求

• 本地网络上的 Victron GX 设备（Ekrano、Cerbo、Venus GX 等）
• MQTT（在 Venus OS 上默认启用）或 Modbus TCP（Settings → Services → Modbus TCP）
• Node.js 18+

---

你可以做什么

能源报告

提示词	功能
hourly-snapshot	快速查看功率流——SOC、PV、电网、负载
daily-report	发电量、能耗、自用比例、电网依赖度
weekly-review	发电趋势、电池健康状况、负载模式、调度建议
monthly-analysis	能源平衡、节省成本、电池老化、季节对比

能源优化

提示词	功能
energy-optimizer	AI 驱动的调优——选择目标：提高自用率、节省成本、延长电池寿命、做好备用准备或保持平衡
ess-tuning	检查 ESS 模式、电网设定值、电池限制、Dynamic ESS
storm-prep	停电前准备情况检查

监控与故障排查

提示词	功能
diagnose-system	全面健康检查并扫描警报
solar-performance	PV 发电量分析、跟踪器对比、遮挡检测
troubleshoot	引导式调试并查询错误代码
tank-monitor	燃油、水、废水液位（船舶 / 房车 / 离网场景）
generator-management	自动启动条件、运行时间、静音时段

设备发现

提示词	功能
setup-guide	首次设置向导
find-devices	扫描网络，发现所有 GX 设备及其连接的设备
identify-device	“单元 ID 247 是什么？”——识别任意设备
system-topology	绘制 AC/DC 母线、连接关系和能源流向
device-inventory	完整设备表，可用于文档或支持
register-explorer	浏览寄存器，说明类型和缩放因子
firmware-check	检查所有设备的固件版本

面向安装人员

提示词	作用
commissioning	新系统检查清单 — 设备清点、接线、配置、通过/失败
site-audit	通信、警报、测量和性能审计

集成

提示词	作用
nodered-check	Venus OS 上的 Node-RED — MQTT 主题、流程调试
mqtt-debug	代理连接、主题追踪、保活调试

---

工具参考

核心监控（9 个工具）

工具	描述
victron_system_overview	电池 SOC、PV 功率、电网功率、AC 消耗、ESS 状态
victron_battery_status	SOC、电压、电流、功率、温度、电芯数据、剩余时间
victron_solar_status	PV 功率、今日/昨日/总发电量、充电器状态、跟踪器数据
victron_grid_status	各相电网功率（L1/L2/L3）、电压、电流、频率
victron_vebus_status	Multi/Quattro：AC 输入/输出、电流限制、模式、状态、警报
victron_tank_levels	液位、容量、剩余量、液体类型
victron_temperature	温度、传感器类型、湿度、气压
victron_inverter_status	独立逆变器：AC 输出、状态、警报
victron_evcs_status	EV Charging Station：功率、状态、充电会话能量

扩展设备（14 个工具）

工具	描述
victron_multi_status	Multi RS 逆变器/充电器
victron_pvinverter_status	AC 耦合型 PV 逆变器（Fronius、SolarEdge、ABB）
victron_genset_status	AC 发电机组控制器
victron_dcgenset_status	DC 发电机
victron_alternator_status	NMEA 2000 交流发电机
victron_charger_status	AC 充电器（Skylla、Blue Smart）
victron_dcdc_status	Orion XS DC-DC 转换器
victron_acload_status	AC 负载/电流传感器
victron_dcenergy_status	DC 电能表（DC 电表模式下的 SmartShunt）
victron_gx_info	GX 设备标识、继电器状态
victron_digital_inputs	数字输入状态和类型
victron_gps_status	GPS 位置、海拔、速度
victron_meteo_status	太阳辐照度、风速、温度
victron_generator_status	发电机自动启停、运行时间、警报

发现与设置（4 个工具）

工具	描述
victron_network_scan	扫描本地网络以查找 GX 设备
victron_setup	完整设置：测试传输方式、发现设备、生成配置
victron_mqtt_discover	自动发现 MQTT 门户 ID、服务和设备实例
victron_discover	扫描 Modbus 单元 ID 以查找已连接设备

实用工具与文档（5 个工具）

工具	描述
victron_read_category	读取任意设备类别的所有寄存器
victron_read_register	按地址读取原始寄存器（仅限 Modbus）
victron_list_registers	列出设备类别可用的寄存器
victron_search_docs	搜索离线文档（寄存器 + VRM API）
victron_check_online	获取最新 Victron 文档的 URL

资源

URI	内容
victron://register-list	CCGX Modbus TCP 寄存器列表（Rev 3.71）— 943 个寄存器
victron://unit-id-mapping	设备类型到单元 ID 的映射

---

配置

环境变量

均为可选。设置这些变量可避免在每次工具调用时重复传入参数。

变量	默认值	描述
VICTRON_HOST	(none)	GX 设备 IP 或主机名
VICTRON_TRANSPORT	modbus	modbus 或 mqtt
VICTRON_PORTAL_ID	(auto)	MQTT 的 Portal ID
VICTRON_MODBUS_PORT	502	Modbus TCP 端口
VICTRON_MQTT_PORT	1883	MQTT 代理端口
VICTRON_UNIT_ID	100	默认 Modbus 单元 ID

远程使用（MCP Connector API）

此软件包使用 stdio 通信，Anthropic MCP Connector API 无法直接访问它（Connector 需要 HTTPS）。如需通过云端访问，请使用配套软件包 victron-vrm-mcp。

如果确实需要让 Connector API 访问此软件包（例如，远程读取原始寄存器），则需要将其置于自建的 HTTPS 网关之后；该网关通过 Streamable HTTP 连接上游，并在下游启动 victron-tcp——一般情况下不建议这样做。

---

调试

MCP Inspector 是交互式试用服务的最快方式。

# Inspect a locally-built server
npm run inspect

# Inspect the published npm package as users would run it
npm run inspect:npm

这两种方式都会打开基于浏览器的 UI，你可以在其中调用工具、查看结构化内容并监视通知流。日志会写入 stderr（stdout 专用于 stdio 传输中的 JSON-RPC 流——切勿写入 stdout）。

对于 Claude Desktop，MCP 服务日志位于 ~/Library/Logs/Claude/mcp-server-victron-tcp.log（macOS）或 %APPDATA%\Claude\logs\mcp-server-victron-tcp.log（Windows）。有关完整操作指南，请参阅规范中的调试指南。

---

文档

指南	内容
配置	客户端配置、传输方式对比、单元 ID、支持的设备
示例	真实场景提示词及 AI 行为逐步说明
故障排查	常见错误及解决方法
常见问题	常见问题解答
架构	代码结构、寄存器映射、工作原理
安全	安全模型、数据敏感性、网络暴露

---

路线图

• 写入支持 — ESS 模式控制、电网设定值、充电电流限制、继电器控制（通过 MQTT W/ 主题）
• MCP 资源 — 寄存器列表和单元 ID 映射（VRM API 规范已移至 victron-vrm-mcp）
• MCP 提示词 — 23 个引导式工作流
• NPM 软件包（npx victron-tcp）
• 用于访问 VRM 云端的配套软件包 — victron-vrm-mcp

参考资料

• Victron Modbus TCP 常见问题
• CCGX 寄存器列表（Excel）
• Venus OS | MQTT 文档
• VRM API | MCP 协议

许可证

MIT