From a Victron Workshop to an MCP Server: How I Cut Hours off Setting Up Solar Monitoring
From a Victron Workshop to an MCP Server: How I Cut Hours off Setting Up Solar Monitoring

·7 min read
Share

It started at a workshop

I recently attended a Victron Energy workshop. The usual playbook came up for building proper monitoring on top of a GX device (Cerbo, Ekrano, Venus GX):

  1. Enable MQTT / Modbus TCP on Venus OS.
  2. Spin up Node-RED - build the flow, wire topics, debug keepalive.
  3. Pipe the data into InfluxDB (or another time-series DB).
  4. Build a dashboard in Grafana - queries, panels, alerts.
  5. Then keep the whole thing running.

For an integrator who does this every day, it’s routine. For a PV owner, a boat skipper, or someone with an off-grid cabin who just wants to ask on Monday morning “how much did I produce yesterday, and will I finish charging before the weather turns?” - it’s a weekend of work just for setup. And that’s before you’ve even looked at what the system is actually doing.

I drove home from the workshop thinking: there has to be a better way.

MCP as a shortcut to the data

I’d already been hacking on the Model Context Protocol for a few months - Anthropic’s open standard that lets AI assistants (Claude, Cursor, Windsurf…) read data and call tools. Instead of building the classic Node-RED → MQTT → InfluxDB → Grafana stack, I asked myself:

What if the dashboard were a conversation? What if, instead of panels, I just asked?

The result is victron-tcp - an MCP server that connects any MCP-capable AI assistant directly to your Victron GX device over the local network. No cloud, no database, no Grafana. And no hours of setup.

By the numbers

  • 32 tools for reading system, battery, PV, grid, inverter, tanks, GPS, EVCS, and more
  • 24 ready-made prompts - from hourly-snapshot to storm-prep to commissioning for installers
  • 900+ registers across 33 device categories - based on Victron’s published CCGX Modbus TCP register reference (Rev 3.71), available offline
  • Two transports: Modbus TCP (default) and MQTT (Venus OS broker)
  • TypeScript, Node.js 18+, MIT license, one-line install via npx victron-tcp

What it looks like in practice

A setup that takes a minute

The old way: find the GX IP, enable the right service in Settings → Services, build a Node-RED flow, verify topics, wire up the DB…

With victron-tcp, you just tell the assistant:

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

Claude calls victron_network_scan, sweeps the subnet, probes ports 502 and 1883, verifies each candidate by reading a system register, and spits out a ready-to-paste config for Claude Desktop / Cursor / Claude Code. That’s a one-minute setup - not a weekend.

A dashboard that’s a conversation

Instead of a Grafana panel, you just ask:

“Show me the current system state - battery, PV, grid.”

The AI calls victron_system_overview and returns SOC, PV power, grid import/export, ESS status. Done.

Want a weekly breakdown?

“Give me a weekly review - yield, battery health, load patterns.”

The weekly-review prompt walks the relevant registers and returns a report, complete with suggestions on how to tune your scheduling.

Need to check readiness before a storm?

“Storm prep - outage incoming.”

The storm-prep prompt checks SOC, inverter state, ESS mode, tanks (generator fuel), relays, and tells you what to lock down.

For installers

What surprised me most was how much installers light up when I show this to them. The commissioning prompt produces a new-install checklist: device inventory, wiring verification, configuration, pass/fail report. site-audit walks an existing install - communication, alarms, measurements, performance - and generates a customer-ready report. Instead of an hour clicking through VictronConnect and VRM.

It’s an assistant, not a replacement for certified commissioning, grid-code compliance checks, or professional judgment.

Why MCP, not yet another app?

The obvious path would have been another web app or a Home Assistant integration. But:

  • Context carries over. The AI remembers what we debugged yesterday and can tie it to today’s data.
  • Reasoning for free. You don’t need to hand-tune alert rules - ask “does this look right?” and get a grounded answer that factors in outside temperature, season, historical data, firmware version.
  • No lock-in. MCP is an open standard. Claude today, anything MCP-capable tomorrow.
  • Local-first. Data never leaves your network. No cloud, no relay server.

Under the hood

  • TypeScript + MCP SDK (@modelcontextprotocol/sdk), modbus-serial for Modbus TCP, mqtt for the Venus OS broker.
  • Unified transport abstraction - whether you go over Modbus or MQTT, tools receive an identical RegisterReadResult. You pick whichever protocol you have enabled; the tools don’t care.
  • Offline register database - Victron ships the register list as an Excel file. A convert-excel.ts script turns it into JSON that the server carries with it, so the AI can explain any register even offline.
  • MQTT auto-discovery - the portal ID is detected automatically via a wildcard subscribe, so there’s nothing to look up by hand.
  • Stateless - every tool call opens a connection, reads, and closes. No long-lived sessions, no leaks.

Read-only - for now

The current release (1.2.0) is read-only. No writes to the device, no changes to ESS mode or grid setpoint. That’s deliberate - before I hand control over to an AI, I want a proper safety model in place.

Write support is on the roadmap: ESS mode changes, grid setpoint, charge current limits, relay control - gated by an operator-approved allowlist and kept within what the grid connection agreement permits. Along with it comes a full layer of safety checks (idempotence, confirmation flows, and an explicit scope of allowed operations).

The takeaway

Victron is an open system - Modbus, MQTT, VRM API, it’s all there already. The ecosystem around it (Node-RED, Grafana, Home Assistant) is excellent. But between “the data exists” and “the user understands it” there are still too many layers.

MCP compresses that gap into a conversation. Instead of hours of setup, you pay a minute of install. Instead of a dashboard, you have a chat. Instead of writing your own alerting, you ask “does this look right?” And when something breaks, the AI walks you through it via the troubleshoot prompt - including error-code lookups against the offline docs.

Grafana and Node-RED aren’t wrong. They’re just not what everyone wants. For the rest, this is a reasonable shortcut.

Try it

Requirements: Node.js 18+, a Victron GX device on your local network, and either MQTT (enabled by default on Venus OS) or Modbus TCP (Settings → Services → Modbus TCP). No API keys, no cloud accounts, no VRM token.

Claude Code - one line:

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

Claude Desktop / Cursor / Windsurf - drop into your MCP config:

{
  "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 GX IP or portal ID? Skip the env block and just ask: “Find my Victron on the network.” The server will scan, probe, and generate a ready-to-paste config.

Repo: github.com/lubosstrejcek/victron-tcp
License: MIT - PRs and issues welcome.

Running a Victron system and kicking the tires on this? Drop me a line about what works and what breaks - feedback from real installs is what will push victron-tcp furthest.

Disclaimer: Independent community project. Not affiliated with, endorsed by, or sponsored by Victron Energy B.V. “Victron,” “Cerbo GX,” “Ekrano GX,” “Venus OS,” “VictronConnect,” and “VRM” are trademarks of their respective owners. AI output can be wrong - verify anything safety-critical against the device and official documentation before acting on it.

L

Lubos Strejcek

Content Writer at STREYDA

Back to Blog
Previous Next