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_setup probes both transports, discovers everything, generates ready-to-use config
- Read-only and safe — all tools annotated with readOnlyHint: true

Prerequisites

1. A Victron GX device on your local network (Ekrano, Cerbo, Venus GX, etc.)
2. MQTT (enabled by default) or Modbus TCP (Settings → Services → Modbus TCP)
3. 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
- [x] Claude Desktop Extension packaging (.mcpb)
- [x] 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