Content
<!-- mcp-name: io.github.lubosstrejcek/victron-tcp -->
# Victron TCP — MCP Server
Connect AI assistants to Victron Energy systems. Read real-time solar, battery, grid, and inverter data from your local network — no cloud required.
> 32 tools | 23 prompts | 2 resources | 900+ registers | Modbus TCP + MQTT
---
## Which package do I want?
This is the **local / LAN** half of a pair. The remote / cloud half is **[`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp)**.
| | **`victron-tcp`** (this repo) | **[`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp)** |
|---|---|---|
| Transport | stdio (local subprocess) | Streamable HTTP (remote) |
| Data source | Modbus TCP + MQTT on your LAN | VRM cloud API |
| Needs access to the GX on your LAN | **Yes** | No |
| Works when you're away from the boat / house | No | **Yes** |
| Works when the internet is down | **Yes** | No |
| Latency | Real-time (~50 ms) | ~15 min (VRM sampling) |
| Raw register access | **Yes** (900+ registers) | No |
| Write coverage (planned) | Broad — anything D-Bus exposes | Narrow — only what VRM sanctions remotely (Dynamic ESS, clear-alarm, tags, …) |
| MCP Connector API compatible | No (stdio) | **Yes** (HTTPS) |
| Clients | Claude Code, Claude Desktop, Cursor, Windsurf | Anthropic Messages API + anything that speaks MCP over HTTP |
| Auth | None locally (trusts LAN) | Per-request VRM personal access token |
**Use this package when:** you're on the same LAN as a GX device and want real-time, low-latency read access with raw-register support.
**Use `victron-vrm-mcp` when:** you need remote access, you're building an API-backed app via the MCP Connector, or you don't want to expose anything on your LAN.
You can use **both** simultaneously — they serve different use cases and carry different risk profiles.
---
## Installation
### 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"
}
}
}
}
```
### Don't know your device IP?
Just ask the AI:
```
Find my Victron GX device on the network and set it up.
```
It will scan your network, test connectivity, and generate the config for you.
### Requirements
- **Victron GX device** on your local network (Ekrano, Cerbo, Venus GX, etc.)
- **MQTT** (enabled by default on Venus OS) or **Modbus TCP** (Settings → Services → Modbus TCP)
- **Node.js 18+**
---
## What you can do
### Energy Reporting
| Prompt | What it does |
|--------|-------------|
| `hourly-snapshot` | Quick power flow snapshot — SOC, PV, grid, load |
| `daily-report` | Production, consumption, self-consumption ratio, grid dependency |
| `weekly-review` | Yield trends, battery health, load patterns, scheduling tips |
| `monthly-analysis` | Energy balance, cost savings, battery aging, seasonal comparison |
### Energy Optimization
| Prompt | What it does |
|--------|-------------|
| `energy-optimizer` | AI-driven tuning — choose goal: self-consumption, cost savings, battery longevity, backup readiness, or balanced |
| `ess-tuning` | Review ESS mode, grid setpoint, battery limits, Dynamic ESS |
| `storm-prep` | Pre-outage readiness check |
### Monitoring & Troubleshooting
| Prompt | What it does |
|--------|-------------|
| `diagnose-system` | Full health check with alarm scan |
| `solar-performance` | PV yield analysis, tracker comparison, shading detection |
| `troubleshoot` | Guided debugging with error code lookup |
| `tank-monitor` | Fuel, water, waste levels (marine/RV/off-grid) |
| `generator-management` | Auto-start conditions, runtime, quiet hours |
### Device Discovery
| Prompt | What it does |
|--------|-------------|
| `setup-guide` | First-time setup wizard |
| `find-devices` | Scan network, discover all GX devices and their connected devices |
| `identify-device` | "What is unit ID 247?" — identify any device |
| `system-topology` | Map AC/DC buses, connections, energy flow paths |
| `device-inventory` | Full device table for documentation or support |
| `register-explorer` | Browse registers, explain types and scale factors |
| `firmware-check` | Firmware versions across all devices |
### For Installers
| Prompt | What it does |
|--------|-------------|
| `commissioning` | New system checklist — inventory, wiring, config, pass/fail |
| `site-audit` | Communication, alarms, measurements, performance audit |
### Integration
| Prompt | What it does |
|--------|-------------|
| `nodered-check` | Node-RED on Venus OS — MQTT topics, flow debugging |
| `mqtt-debug` | Broker connectivity, topic tracing, keepalive debugging |
---
## Tools Reference
<details>
<summary><strong>Core Monitoring (9 tools)</strong></summary>
| Tool | Description |
|------|-------------|
| `victron_system_overview` | Battery SOC, PV power, grid power, AC consumption, ESS status |
| `victron_battery_status` | SOC, voltage, current, power, temperature, cell data, time-to-go |
| `victron_solar_status` | PV power, yield today/yesterday/total, charger state, tracker data |
| `victron_grid_status` | Grid power per phase (L1/L2/L3), voltage, current, frequency |
| `victron_vebus_status` | Multi/Quattro: AC in/out, current limit, mode, state, alarms |
| `victron_tank_levels` | Tank level, capacity, remaining, fluid type |
| `victron_temperature` | Temperature, sensor type, humidity, pressure |
| `victron_inverter_status` | Standalone inverter: AC output, state, alarms |
| `victron_evcs_status` | EV Charging Station: power, status, session energy |
</details>
<details>
<summary><strong>Extended Devices (14 tools)</strong></summary>
| Tool | Description |
|------|-------------|
| `victron_multi_status` | Multi RS inverter/charger |
| `victron_pvinverter_status` | AC-coupled PV inverters (Fronius, SolarEdge, ABB) |
| `victron_genset_status` | AC genset controllers |
| `victron_dcgenset_status` | DC generators |
| `victron_alternator_status` | NMEA 2000 alternators |
| `victron_charger_status` | AC chargers (Skylla, Blue Smart) |
| `victron_dcdc_status` | Orion XS DC-DC converter |
| `victron_acload_status` | AC load / current sensors |
| `victron_dcenergy_status` | DC energy meters (SmartShunts in DC meter mode) |
| `victron_gx_info` | GX device identity, relay states |
| `victron_digital_inputs` | Digital input state and type |
| `victron_gps_status` | GPS position, altitude, speed |
| `victron_meteo_status` | Solar irradiance, wind speed, temperatures |
| `victron_generator_status` | Generator auto start/stop, runtime, alarms |
</details>
<details>
<summary><strong>Discovery & Setup (4 tools)</strong></summary>
| Tool | Description |
|------|-------------|
| `victron_network_scan` | Scan local network to find GX devices |
| `victron_setup` | Full setup: test transports, discover devices, generate config |
| `victron_mqtt_discover` | Auto-discover MQTT portal ID, services, device instances |
| `victron_discover` | Scan Modbus unit IDs to find connected devices |
</details>
<details>
<summary><strong>Utility & Documentation (5 tools)</strong></summary>
| Tool | Description |
|------|-------------|
| `victron_read_category` | Read all registers for any device category |
| `victron_read_register` | Read raw register(s) by address (Modbus only) |
| `victron_list_registers` | List available registers for a device category |
| `victron_search_docs` | Search offline docs (registers + VRM API) |
| `victron_check_online` | Get URLs for latest Victron docs |
</details>
### Resources
| URI | Content |
|-----|---------|
| `victron://register-list` | CCGX Modbus TCP register list (Rev 3.71) — 943 registers |
| `victron://unit-id-mapping` | Device type to unit ID mapping |
---
## Configuration
### Environment Variables
All optional. Set them to avoid repeating parameters on every tool call.
| Variable | Default | Description |
|----------|---------|-------------|
| `VICTRON_HOST` | _(none)_ | GX device IP or hostname |
| `VICTRON_TRANSPORT` | `modbus` | `modbus` or `mqtt` |
| `VICTRON_PORTAL_ID` | _(auto)_ | Portal ID for MQTT |
| `VICTRON_MODBUS_PORT` | `502` | Modbus TCP port |
| `VICTRON_MQTT_PORT` | `1883` | MQTT broker port |
| `VICTRON_UNIT_ID` | `100` | Default Modbus unit ID |
### Remote usage (MCP Connector API)
This package speaks **stdio**, which the [Anthropic MCP Connector API](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) cannot reach directly (Connector needs HTTPS). For cloud-backed remote access, use the sibling package [`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp).
If you really need the Connector API to reach *this* package (e.g. to use raw register reads remotely), you'd put it behind your own HTTPS gateway that speaks Streamable HTTP upstream and spawns `victron-tcp` downstream — not recommended for typical use.
---
## Debugging
The [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is the fastest way to poke at the server interactively.
```bash
# Inspect a locally-built server
npm run inspect
# Inspect the published npm package as users would run it
npm run inspect:npm
```
Both open a browser-based UI where you can call tools, view structured content, and watch the notification stream. Logs go to **stderr** (stdout is reserved for the JSON-RPC stream on stdio transport — never write to stdout).
For Claude Desktop specifically, MCP server logs land in `~/Library/Logs/Claude/mcp-server-victron-tcp.log` (macOS) or `%APPDATA%\Claude\logs\mcp-server-victron-tcp.log` (Windows). See the spec's [debugging guide](https://modelcontextprotocol.io/docs/tools/debugging) for a full walkthrough.
---
## Documentation
| Guide | Content |
|-------|---------|
| [Setup](docs/setup.md) | Client configs, transport comparison, unit IDs, supported devices |
| [Examples](docs/examples.md) | Real-world prompts with step-by-step AI behavior |
| [Troubleshooting](docs/troubleshooting.md) | Common errors and fixes |
| [FAQ](docs/faq.md) | Frequently asked questions |
| [Architecture](docs/architecture.md) | Code structure, register map, how it works |
| [Security](SECURITY.md) | Security model, data sensitivity, network exposure |
---
## Roadmap
- [ ] **Write support** — ESS mode control, grid setpoint, charge current limits, relay control (via MQTT `W/` topics)
- [x] MCP Resources — register list + unit ID mapping (VRM API spec moved to [`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp))
- [x] MCP Prompts — 23 guided workflows
- [x] NPM package (`npx victron-tcp`)
- [x] Sibling package for VRM cloud access — [`victron-vrm-mcp`](https://github.com/lubosstrejcek/victron-vrm-mcp)
## References
- [Victron Modbus TCP FAQ](https://www.victronenergy.com/live/ccgx:modbustcp_faq)
- [CCGX Register List (Excel)](https://www.victronenergy.com/support-and-downloads/technical-information)
- [Venus OS](https://github.com/victronenergy/venus) | [MQTT docs](https://github.com/victronenergy/dbus-mqtt)
- [VRM API](https://vrm-api-docs.victronenergy.com/) | [MCP Protocol](https://modelcontextprotocol.io)
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available