MCP SERVERRead a Victron installation over Modbus TCP or MQTT: battery state of charge, solar yield, grid and inverter power, tank levels, alternator and genset data — and find the GX device on the network first.
LABSCO SUMMARY
This talks to the device on your own network rather than to Victron's portal, which is what makes it usable off-grid and on a boat with no connectivity. Start with the setup call: it tests both transports, finds what is connected, and saves you guessing which family tool applies to your hardware. Keep the raw register tools in reserve — they cover whatever the decoded tools do not, and the bundled offline register list is what turns an address into a meaning without a browser.
A reader for Victron GX systems on your own network. One tool per device family returns that family's live values already decoded, and the raw register tools are there for anything the decoded set does not cover.
Network reach to the GX device, and Modbus TCP enabled on it. VICTRON_HOST names the device, but it is optional — the host can be passed per call, or found with the network scan. VICTRON_TRANSPORT chooses modbus or mqtt, defaulting to modbus; MQTT additionally wants VICTRON_PORTAL_ID for its topics. Ports default to 502 for Modbus and 1883 for MQTT, and the default Modbus unit ID is 100. Raw register reads are Modbus TCP only and are not available over MQTT. It runs on Node over stdio as npx victron-tcp. MIT.
One command — npx -y victron-tcp
USE CASES
One overview call gives battery state of charge, solar production, grid draw and inverter state — the numbers you would walk over to the panel for.
Read yield today against yesterday and the total from the charger, and compare it with grid import and AC consumption.
Scan the network for the GX, run the combined setup to test both transports, and probe unit IDs to see which devices actually answer.
Read tank levels with their fluid types, temperatures, GPS position, and the alternator's output while the engine runs.
Read the genset controller's own AC output and the GX's auto start/stop state, including the condition that triggered a start.
Find the register in the offline list with its address, type and scale factor, then read it directly over Modbus TCP.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
victron_acload_statusGet AC load and current sensor data: per-phase power, voltage, current, energy totals, frequency, and power factor. Used for AC current sensors measuring PV inverter output or other AC loads. Use victron_discover to find the unit ID.
victron_alternator_statusGet alternator data from Wakespeed WS500, Arco Zeus, Revatek Altion, or other NMEA 2000 DC alternator regulators: battery voltage/current, auxiliary voltage, temperature, energy produced, engine/alternator RPM, field drive %, alarms, and state. Use victron_discover to find the unit ID.
victron_battery_statusGet detailed battery monitor data: SOC, voltage, current, power, temperature, cell voltages, time-to-go, history, and alarms. Specify unitId for the battery monitor (check victron_discover to find it).
victron_charger_statusGet AC charger data (Skylla-i, Skylla-IP44, Smart IP43, Blue Smart IP22): output voltage/current/temperature for up to 3 outputs, AC current/power, charge state, error code, current limit, and alarms. Use victron_discover to find the unit ID.
victron_check_onlineGet URLs for the latest Victron local-access documentation sources. Use this only when victron_search_docs does not have the answer — for example, when checking for newer register list revisions or firmware changes. For VRM cloud API docs, use the victron-vrm-mcp sibling package.
victron_dcdc_statusGet Orion XS DC-DC converter data: battery voltage/current/temperature, input voltage/power, charge state, error code, switch position, and accumulated Ah. Use victron_discover to find the unit ID.
victron_dcenergy_statusGet DC energy meter data from SmartShunts configured in DC meter mode: voltage, current, auxiliary voltage, temperature, energy produced/consumed, and alarms. Specify type: "source" (alternator, solar, wind), "load" (fridge, pump, generic DC load), or "system" (aggregate DC system). Unit ID is always 100.
victron_dcgenset_statusGet DC generator data (Fischer Panda, Hatz fiPMG): DC voltage/current, engine load/speed/RPM, coolant/winding/exhaust temperature, oil pressure, starter battery voltage, status, error codes, and start command. Use victron_discover to find the unit ID.
victron_digital_inputsRead digital input data from the GX device. On Cerbo GX, this reads the primary digital input. Includes state (open/closed/running/stopped), input type (door, bilge, alarm, generator), alarm status, and pulse count. Unit ID is always 100.
victron_discoverDiscover connected Victron devices via Modbus TCP by probing unit IDs. Scans a range of unit IDs to find active devices and identify their service type. Modbus only — for MQTT discovery use victron_mqtt_discover instead. This is the first tool you should use with Modbus transport to find what devices are available and their unit IDs.
victron_evcs_statusGet EV Charging Station status by connecting directly to the EVCS device (not through the GX). Reads charger status, power per phase, charging current, session energy, mode, phase configuration, temperatures, and errors. The host parameter should be the EVCS IP address (not the GX). For EV charger data proxied through the GX device, use victron_read_category with category "evcharger" instead.
victron_generator_statusGet GX generator auto start/stop status and control: manual start/stop command, start condition (SOC/load/voltage/manual), runtime, quiet hours, start/stop state, auto start enabled, service countdown, and alarms. This controls the GX relay-based generator start/stop logic. Unit ID is always 100.
victron_genset_statusGet AC generator/genset controller data (Fischer Panda, ComAp, DSE, CRE, DEIF): 3-phase AC voltage/current/power/frequency, engine temperature/load/speed/RPM, oil pressure, coolant temperature, exhaust temperature, starter voltage, model name, and error codes. Use victron_discover to find the unit ID.
victron_gps_statusGet GPS position data: latitude, longitude, altitude, course, speed, fix status, and number of satellites. Works with USB GPS (NMEA 0183) and NMEA 2000 GPS devices connected to the GX. Unit ID is always 100.
victron_grid_statusGet grid meter data: power per phase (L1/L2/L3), voltage, current, frequency, and energy counters (forward/reverse). Specify unitId for the grid meter (check victron_discover to find it).
victron_gx_infoGet GX device identity and connection info: serial number, relay states, system time, and connection details. MAC address and hostname are NOT available via Modbus TCP. Unit ID is always 100.
victron_inverter_statusGet standalone inverter data (Phoenix, Inverter RS, VE.Direct inverters): AC output voltage, current, power, frequency, state, and alarms. This is for standalone inverters — for Multi/Quattro, use victron_vebus_status instead.
victron_list_registersList available Modbus registers for a given device category. Shows register addresses, names, data types, and units. For free-text search across all docs use victron_search_docs instead.
victron_meteo_statusGet meteorological sensor data from IMT Solar irradiance sensors: solar irradiance (W/m²), wind speed, cell temperature, and external temperatures. Connected via RS485/USB. Unit ID is always 100.
victron_mqtt_discoverDiscover Venus OS devices via MQTT. Auto-discovers the portalId, lists all available services, maps them to tools, and outputs a ready-to-use MCP server config. Run this first when setting up MQTT transport.
victron_multi_statusGet Multi RS inverter/charger data: AC input/output voltage/current/power per phase, input frequency, AC source type, current limits, battery voltage/current/power/SOC/temperature, charger/inverter state, and alarms. Use victron_discover to find the unit ID.
victron_network_scanScan the local network to find Victron GX devices. Probes for Modbus TCP (port 502) and MQTT (port 1883) services, then verifies Victron devices via Modbus. Use this when you don't know the IP address of the GX device. Specify a subnet or let it auto-detect from local network interfaces.
victron_pvinverter_statusGet AC-coupled PV inverter data (SolarEdge, Fronius, ABB, etc.): power per phase, voltage, current, energy totals, frequency, position, serial, and power limit. Use victron_discover to find the PV inverter unit ID.
victron_read_categoryRead all registers for any Victron device category by service name. Covers all 33 categories including digital inputs, genset, PV inverter, settings, GPS, meteo, and more. Use victron_discover to find connected devices and their unit IDs first.
victron_read_registerRead raw Modbus register(s). Modbus TCP only — not available via MQTT. Advanced tool for reading specific register addresses with explicit data type and scale factor. Use victron_search_docs or victron_list_registers first to find the correct address, data type, and scale factor for the register you want to read.
victron_search_docsSearch the local offline Victron register list (900+ registers with addresses, types, scale factors). Use this BEFORE making online requests — the local docs cover most questions about registers, unit IDs, data types, and device categories. For VRM cloud API search, use the victron-vrm-mcp sibling package.
victron_setupComplete system setup and discovery for a Victron GX device. Tests both Modbus TCP and MQTT connectivity, discovers all connected devices and services, recommends the best transport, and generates ready-to-use MCP server configuration. Use this as the first step after finding a device with victron_network_scan, or directly if you already know the host IP.
victron_solar_statusGet solar charger data: PV voltage, current, power, yield today/yesterday/total, charger state, error code, and tracker data. Specify unitId for the solar charger (check victron_discover to find it).
victron_system_overviewGet system overview: battery SOC/voltage/current/power, PV power, grid power, AC consumption, inverter state, and Dynamic ESS status. Unit ID is always 100.
victron_tank_levelsGet tank sensor data: level, capacity, remaining, and fluid type (fuel, fresh water, waste water, live well, oil, black water, gasoline). Specify unitId for the tank sensor (check victron_discover to find it).
victron_temperatureGet temperature sensor data from com.victronenergy.temperature: temperature, type (battery, fridge, generic), humidity, pressure, and status. Note: Battery temperatures measured by inverters/chargers or solar chargers are reported in their own device registers (use victron_vebus_status or victron_solar_status), not here. This tool reads dedicated temperature sensor inputs only. Specify unitId for the temperature sensor (check victron_discover to find it).
victron_vebus_statusGet VE.Bus inverter/charger (Multi/Quattro) data: AC input/output voltage, current, power per phase, DC voltage, input current limit, mode, state, alarms, and ESS settings. Specify unitId for the VE.Bus device (check victron_discover to find it).
BEFORE YOU INSTALL
32 tools when we connected.
CONTEXT COST
Rated by the size of the 32 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
npx -y victron-tcpclaude mcp add-json victron-tcp '{"type":"stdio","command":"npx","args":["-y","victron-tcp"]}'{
"mcpServers": {
"victron-tcp": {
"command": "npx",
"args": [
"-y",
"victron-tcp"
],
"env": {
"VICTRON_HOST": "192.168.1.50",
"VICTRON_TRANSPORT": "mqtt",
"VICTRON_PORTAL_ID": "<YOUR_VICTRON_PORTAL_ID>"
}
}
}
}MCP servers
paulomac1000
AndrewKlement
randybritsch
rhoegg