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

Extended Devices

Discovery & Setup

Utility

Environment Variables

Set these to skip repetitive parameters:

Documentation

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