Victron TCP — MCP Server

Connect AI assistants to Victron Energy systems. Read real-time solar, battery, grid, and inverter data from your local network — no cloud required.

> 32 tools | 23 prompts | 2 resources | 900+ registers | Modbus TCP + MQTT

Which package do I want?

This is the local / LAN half of a pair. The remote / cloud half is **`victron-vrm-mcp`**.

Use this package when: you're on the same LAN as a GX device and want real-time, low-latency read access with raw-register support.

Use `victron-vrm-mcp` when: you need remote access, you're building an API-backed app via the MCP Connector, or you don't want to expose anything on your LAN.

You can use both simultaneously — they serve different use cases and carry different risk profiles.

Installation

Claude Code

claude mcp add-json victron-tcp '{"type":"stdio","command":"npx","args":["-y","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"
      }
    }
  }
}

Don't know your device IP?

Just ask the AI:

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

It will scan your network, test connectivity, and generate the config for you.

Requirements

• Victron GX device on your local network (Ekrano, Cerbo, Venus GX, etc.)
• MQTT (enabled by default on Venus OS) or Modbus TCP (Settings → Services → Modbus TCP)
• Node.js 18+

What you can do

Energy Reporting

Energy Optimization

Monitoring & Troubleshooting

Device Discovery

For Installers

Integration

Tools Reference

Core Monitoring (9 tools)

Extended Devices (14 tools)

Discovery & Setup (4 tools)

Utility & Documentation (5 tools)

Resources

Configuration

Environment Variables

All optional. Set them to avoid repeating parameters on every tool call.

Remote usage (MCP Connector API)

This package speaks stdio, which the Anthropic MCP Connector API cannot reach directly (Connector needs HTTPS). For cloud-backed remote access, use the sibling package `victron-vrm-mcp`.

If you really need the Connector API to reach *this* package (e.g. to use raw register reads remotely), you'd put it behind your own HTTPS gateway that speaks Streamable HTTP upstream and spawns `victron-tcp` downstream — not recommended for typical use.

Debugging

The MCP Inspector is the fastest way to poke at the server interactively.

# Inspect a locally-built server
npm run inspect

# Inspect the published npm package as users would run it
npm run inspect:npm

Both open a browser-based UI where you can call tools, view structured content, and watch the notification stream. Logs go to stderr (stdout is reserved for the JSON-RPC stream on stdio transport — never write to stdout).

For Claude Desktop specifically, MCP server logs land in `~/Library/Logs/Claude/mcp-server-victron-tcp.log` (macOS) or `%APPDATA%\Claude\logs\mcp-server-victron-tcp.log` (Windows). See the spec's debugging guide for a full walkthrough.

Documentation

Roadmap

• [ ] Write support — ESS mode control, grid setpoint, charge current limits, relay control (via MQTT `W/` topics)
• [x] MCP Resources — register list + unit ID mapping (VRM API spec moved to `victron-vrm-mcp`)
• [x] MCP Prompts — 23 guided workflows
• [x] NPM package (`npx victron-tcp`)
• [x] Sibling package for VRM cloud access — `victron-vrm-mcp`

References

• Victron Modbus TCP FAQ
• CCGX Register List (Excel)
• Venus OS | MQTT docs
• VRM API | MCP Protocol

License

MIT