Victron TCP
An MCP (Model Context Protocol) server that connects to Victron Energy GX devices via Modbus TCP or MQTT on your local network. Get direct, low-latency access to real-time solar, battery, grid, and inverter data — no cloud required.
Built from the official CCGX Modbus TCP register list (Rev 50, 900+ registers across 33 device categories).
Features
30 specialized tools for reading Victron device data
Dual transport — Modbus TCP (port 502) or MQTT (port 1883)
900+ registers across 33 device categories
Network discovery — scan the local network to find GX devices, no IP needed
One-shot setup — victron_setup probes both transports, discovers everything, generates ready-to-use config
Read-only and safe — all tools annotated with readOnlyHint: true
Overview
Victron TCP — MCP Server
An MCP (Model Context Protocol) server that connects to Victron Energy GX devices on your local network via MQTT (recommended) or Modbus TCP. Get direct, low-latency access to real-time solar, battery, grid, and inverter data — no cloud required.
900+ registers across 33 device categories, built from the official CCGX Modbus TCP register list (Rev 50). MQTT transport uses the Venus OS built-in broker for zero-config auto-discovery.
Features
- 30 specialized tools for reading Victron device data
- Dual transport — MQTT (port 1883, zero-config) or Modbus TCP (port 502, raw register access)
- 900+ registers across 33 device categories
- Network discovery — scan the local network to find GX devices, no IP needed
- One-shot setup —
victron_setupprobes both transports, discovers everything, generates ready-to-use config - Read-only and safe — all tools annotated with
readOnlyHint: true
Prerequisites
- A Victron GX device on your local network (Ekrano, Cerbo, Venus GX, etc.)
- MQTT (enabled by default) or Modbus TCP (Settings → Services → Modbus TCP)
- Node.js 18+
Quick Start
Claude Code (recommended)
claude mcp add --transport stdio victron-tcp -- npx victron-tcp
With environment variables pre-configured:
claude mcp add --transport stdio \
-e VICTRON_HOST=192.168.1.50 \
-e VICTRON_TRANSPORT=mqtt \
-e VICTRON_PORTAL_ID=ca0f0e2e2261 \
victron-tcp -- npx 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"
}
}
}
}
See docs/setup.md for per-client config paths, project/user scopes, and building from source.
Don't know your GX device IP?
Ask the AI:
Find my Victron GX device on the network and set it up.
The AI will use victron_network_scan to find it, then victron_setup to configure everything.
Available Tools
Core Monitoring
| 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 (direct connection): power, status, session energy |
Extended Devices
| 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 |
Discovery & Setup
| Tool | Description |
|---|---|
victron_network_scan | Scan local network to find GX devices by probing Modbus TCP and MQTT ports |
victron_setup | Full system setup: test transports, discover devices, generate MCP config |
victron_mqtt_discover | Auto-discover MQTT portal ID, services, and device instances |
victron_discover | Scan Modbus unit IDs to find all connected devices |
Utility
| Tool | Description |
|---|---|
victron_read_category | Read all registers for any device category by service name |
victron_read_register | Read raw register(s) by address (Modbus only) |
victron_list_registers | List available registers for a device category |
Environment Variables
Set these to skip repetitive parameters:
| Variable | Description | Example |
|---|---|---|
VICTRON_HOST | GX device IP or hostname | 192.168.1.50 |
VICTRON_TRANSPORT | modbus or mqtt | mqtt |
VICTRON_PORTAL_ID | Portal ID for MQTT | ca0f0e2e2261 |
VICTRON_MODBUS_PORT | Modbus TCP port | 502 |
VICTRON_MQTT_PORT | MQTT broker port | 1883 |
VICTRON_UNIT_ID | Default Modbus unit ID | 100 |
Documentation
| Guide | Content |
|---|---|
| Setup | Client configuration, transport comparison, finding unit IDs, supported devices |
| Examples | 15 real-world prompts with step-by-step AI behavior |
| Troubleshooting | Common errors and debugging |
| FAQ | Frequently asked questions |
| Architecture | Code structure, how it works, register map |
Roadmap
- Phase 2: Write support — ESS mode control, grid setpoint, charge current limits, relay control
- Phase 3: Resources — expose live device data as MCP resources with subscription notifications for real-time updates
- Claude Desktop Extension packaging (
.mcpb) - NPM package publishing (
npx victron-tcp)
References
- Victron Modbus TCP FAQ
- CCGX Modbus TCP Register List (Excel)
- Venus OS on GitHub
- MCP Protocol Specification
- Venus OS MQTT documentation
License
MIT
Server 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"
}
}
}
}Project Info
Created At
4 months agoUpdated At
3 months agoAuthor Name
lubosstrejcekStar
-Language
-License
-Tags