内容
<!-- mcp-name: io.github.lubosstrejcek/victron-tcp -->
# 维可特 TCP — MCP 服务器
连接 AI 助手到维可特能源系统。读取本地网络中的实时太阳能、电池、电网和逆变器数据 — 无需云服务。
> 32 个工具 | 23 个提示 | 2 个资源 | 900+ 个寄存器 | Modbus TCP + MQTT
---
## 我需要哪个软件包？
这是 **本地 / LAN** 部分的配套软件。远程 / 云端部分是 **[`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp)**。
| | **`victron-tcp`**（此仓库） | **[`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp)** |
|---|---|---|
| 传输方式 | stdio（本地子进程） | Streamable HTTP（远程） |
| 数据源 | Modbus TCP + MQTT 在您的 LAN 上 | VRM 云 API |
| 需要访问 LAN 上的 GX 设备 | **是** | 否 |
| 在远离船只/房屋时是否有效 | 否 | **是** |
| 在互联网断开时是否有效 | **是** | 否 |
| 延迟 | 实时（~50 毫秒） | ~15 分钟（VRM 采样） |
| 原始寄存器访问 | **是**（900+ 个寄存器） | 否 |
| 写覆盖（计划） | 广泛 — 任何 D-Bus 暴露的内容 | 狭窄 — 只有 VRM 远程允许的内容（动态 ESS、清除警报、标签等） |
| MCP 连接器 API 兼容性 | 否（stdio） | **是**（HTTPS） |
| 客户端 | Claude Code、Claude Desktop、Cursor、Windsurf | Anthropic Messages API + 任何通过 HTTP 使用 MCP 的客户端 |
| 身份验证 | 本地无（信任 LAN） | 每个请求的 VRM 个人访问令牌 |
**使用此软件包时：** 您在同一 LAN 上拥有 GX 设备，并希望实时、低延迟地读取原始寄存器数据。
**使用 `victron-vrm-mcp` 时：** 您需要远程访问，正在通过 MCP 连接器构建 API 支持的应用程序，或者不想在 LAN 上暴露任何内容。
您可以同时使用 **两者** — 它们服务于不同的用例，并具有不同的风险特征。
---
## 安装
### Claude Code
```bash
claude mcp add-json victron-tcp '{"type":"stdio","command":"npx","args":["-y","victron-tcp"]}'
```
### Claude Desktop / Cursor / Windsurf
```json
{
"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：
```
在网络上查找我的维可特 GX 设备并进行设置。
```
它将扫描您的网络，测试连接性，并为您生成配置。
### 要求
- **维可特 GX 设备** 在您的本地网络上（Ekrano、Cerbo、Venus GX 等）
- **MQTT** （在 Venus OS 上默认启用）或 **Modbus TCP** （设置 → 服务 → Modbus TCP）
- **Node.js 18+**
---
## 您可以使用
### 能量报告
| 提示 | 功能 |
|--------|-------------|
| `hourly-snapshot` | 快速的电力流动快照 — SOC、PV、电网、负载 |
| `daily-report` | 生产、消费、自消费比率、电网依赖 |
| `weekly-review` | 产量趋势、电池健康状况、负载模式、调度提示 |
| `monthly-analysis` | 能量平衡、成本节约、电池老化、季节比较 |
### 能量优化
| 提示 | 功能 |
|--------|-------------|
| `energy-optimizer` | AI 驱动的调优 — 选择目标：自消费、成本节约、电池寿命、备份准备或平衡 |
| `ess-tuning` | 查看 ESS 模式、电网设定点、电池限制、动态 ESS |
| `storm-prep` | 停电前准备检查 |
### 监控和故障排除
| 提示 | 功能 |
|--------|-------------|
| `diagnose-system` | 完整的健康检查，带有警报扫描 |
| `solar-performance` | 光伏产量分析、跟踪器比较、阴影检测 |
| `troubleshoot` | 有指导的调试，带有错误代码查找 |
| `tank-monitor` | 燃料、水、废物水平（船舶/RV/离网） |
| `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` | 代理连接性、主题跟踪、保持活动调试 |
---
## 工具参考
<details>
<summary><strong>核心监控（9 个工具）</strong></summary>
| 工具 | 描述 |
|------|-------------|
| `victron_system_overview` | 电池 SOC、光伏功率、电网功率、交流消耗量、ESS 状态 |
| `victron_battery_status` | SOC、电压、电流、功率、温度、电池数据、剩余时间 |
| `victron_solar_status` | 光伏功率、今日/昨日/总产量、充电器状态、跟踪器数据 |
| `victron_grid_status` | 每相电网功率（L1/L2/L3）、电压、电流、频率 |
| `victron_vebus_status` | 多/四象限：交流输入/输出、电流限制、模式、状态、警报 |
| `victron_tank_levels` | 油箱液位、容量、剩余量、液体类型 |
| `victron_temperature` | 温度、传感器类型、湿度、压力 |
| `victron_inverter_status` | 独立逆变器：交流输出、状态、警报 |
| `victron_evcs_status` | 电动汽车充电站：功率、状态、会话能量 |
</details>
<details>
<summary><strong>扩展设备（14 个工具）</strong></summary>
| 工具 | 描述 |
|------|-------------|
| `victron_multi_status` | 多 RS 逆变器/充电器 |
| `victron_pvinverter_status` | AC 耦合光伏逆变器（Fronius、SolarEdge、ABB） |
| `victron_genset_status` | 交流发电机控制器 |
| `victron_dcgenset_status` | 直流发电机 |
| `victron_alternator_status` | NMEA 2000 交流发电机 |
| `victron_charger_status` | 交流充电器（Skylla、Blue Smart） |
| `victron_dcdc_status` | Orion XS 直流-直流转换器 |
| `victron_acload_status` | 交流负载/电流传感器 |
| `victron_dcenergy_status` | 直流能量表（SmartShunts 在直流表模式下） |
| `victron_gx_info` | GX 设备标识、中继状态 |
| `victron_digital_inputs` | 数字输入状态和类型 |
| `victron_gps_status` | GPS 位置、海拔、速度 |
| `victron_meteo_status` | 太阳辐照度、风速、温度 |
| `victron_generator_status` | 发电机自动启动/停止、运行时、警报 |
</details>
<details>
<summary><strong>发现和设置（4 个工具）</strong></summary>
| 工具 | 描述 |
|------|-------------|
| `victron_network_scan` | 扫描本地网络以查找 GX 设备 |
| `victron_setup` | 完整设置：测试传输、发现设备、生成配置 |
| `victron_mqtt_discover` | 自动发现 MQTT 门户 ID、服务、设备实例 |
| `victron_discover` | 扫描 Modbus 单元 ID 以查找连接的设备 |
</details>
<details>
<summary><strong>实用程序和文档（5 个工具）</strong></summary>
| 工具 | 描述 |
|------|-------------|
| `victron_read_category` | 读取任何设备类别的所有寄存器 |
| `victron_read_register` | 按地址读取原始寄存器（仅 Modbus） |
| `victron_list_registers` | 列出设备类别的可用寄存器 |
| `victron_search_docs` | 搜索离线文档（寄存器 + VRM API） |
| `victron_check_online` | 获取最新维可特文档的网址 |
</details>
### 资源
| URI | 内容 |
|-----|---------|
| `victron://register-list` | CCGX Modbus TCP 注册表列表（修订版 3.71）— 943 个寄存器 |
| `victron://unit-id-mapping` | 设备类型到单元 ID 映射 |
---
## 配置
### 环境变量
所有变量均为可选。设置它们以避免在每次工具调用时重复参数。
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `VICTRON_HOST` | _(无)_ | GX 设备 IP 或主机名 |
| `VICTRON_TRANSPORT` | `modbus` | `modbus` 或 `mqtt` |
| `VICTRON_PORTAL_ID` | _(自动)_ | MQTT 的门户 ID |
| `VICTRON_MODBUS_PORT` | `502` | Modbus TCP 端口 |
| `VICTRON_MQTT_PORT` | `1883` | MQTT 代理端口 |
| `VICTRON_UNIT_ID` | `100` | 默认 Modbus 单元 ID |
### 远程使用（MCP 连接器 API）
此软件包使用 **stdio**，而 [Anthropic MCP Connector API](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) 无法直接访问（连接器需要 HTTPS）。对于云端远程访问，请使用配套软件包 [`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp)。
如果您确实需要连接器 API 访问 **此** 软件包（例如，远程读取原始寄存器），您需要将其置于自己的 HTTPS 网关后面，该网关使用 Streamable HTTP 上游并在下游启动 `victron-tcp` — 不建议用于典型使用。
---
## 调试
[MCP 检查器](https://modelcontextprotocol.io/docs/tools/inspector) 是交互式调试的最快方法。
```bash
# 检查本地构建的服务器
npm run inspect
# 检查已发布的 npm 包，用户会这样运行
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）。请参阅规范的 [调试指南](https://modelcontextprotocol.io/docs/tools/debugging)，以获取完整的演练。
---
## 文档
| 指南 | 内容 |
|-------|---------|
| [设置](docs/setup.md) | 客户端配置、传输比较、单元 ID、支持的设备 |
| [示例](docs/examples.md) | 具有逐步 AI 行为的现实世界提示 |
| [故障排除](docs/troubleshooting.md) | 常见错误和修复 |
| [FAQ](docs/faq.md) | 常见问题 |
| [架构](docs/architecture.md) | 代码结构、寄存器映射、工作原理 |
| [安全](SECURITY.md) | 安全模型、数据敏感性、网络暴露 |
---
## 路线图
- [ ] **写入支持** — ESS 模式控制、电网设定点、充电电流限制、中继控制（通过 MQTT `W/` 主题）
- [x] MCP 资源 — 注册表列表 + 单元 ID 映射（VRM API 规范移至 [`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp)）
- [x] MCP 提示 — 23 个引导工作流
- [x] NPM 包（`npx victron-tcp`）
- [x] 用于 VRM 云访问的配套软件包 — [`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp)
## 参考
- [维可特 Modbus TCP 常见问题](https://www.victronenergy.com/live/ccgx:modbustcp_faq)
- [CCGX 注册表列表（Excel）](https://www.victronenergy.com/support-and-downloads/technical-information)
- [Venus OS](https://github.com/victronenergy/venus) | [MQTT 文档](https://github.com/victronenergy/dbus-mqtt)
- [VRM API](https://vrm-api-docs.victronenergy.com/) | [MCP 协议](https://modelcontextprotocol.io)
## 许可证
MIT
