Victron ModBus TCP

Servidor que se conecta a dispositivos Victron Energy GX en la red local.

Documentación

Victron TCP — Servidor MCP

Conecta asistentes de IA a sistemas Victron Energy. Lee datos en tiempo real de solar, batería, red e inversor desde tu red local — sin necesidad de nube.

32 herramientas | 23 prompts | 2 recursos | 900+ registros | Modbus TCP + MQTT

¿Qué paquete quiero?

Esta es la mitad local / LAN de un par. La mitad remota / nube es victron-vrm-mcp.

	`victron-tcp` (este repositorio)	`victron-vrm-mcp`
Transporte	stdio (subproceso local)	Streamable HTTP (remoto)
Fuente de datos	Modbus TCP + MQTT en tu LAN	API de nube VRM
Necesita acceso al GX en tu LAN	Sí	No
Funciona cuando estás lejos del barco / casa	No	Sí
Funciona cuando internet está caído	Sí	No
Latencia	Tiempo real (~50 ms)	~15 min (muestreo VRM)
Acceso a registros crudos	Sí (900+ registros)	No
Cobertura de escritura (planificada)	Amplia — todo lo que D-Bus expone	Estrecha — solo lo que VRM permite remotamente (Dynamic ESS, clear-alarm, tags, …)
Compatible con MCP Connector API	No (stdio)	Sí (HTTPS)
Clientes	Claude Code, Claude Desktop, Cursor, Windsurf	Anthropic Messages API + cualquier cosa que hable MCP sobre HTTP
Autenticación	Ninguna localmente (confía en la LAN)	Token de acceso personal VRM por solicitud

Usa este paquete cuando: estés en la misma LAN que un dispositivo GX y quieras acceso de lectura en tiempo real, de baja latencia, con soporte de registros crudos. Usa victron-vrm-mcp cuando: necesites acceso remoto, estés construyendo una app respaldada por API vía MCP Connector, o no quieras exponer nada en tu LAN.

Puedes usar ambos simultáneamente — sirven para diferentes casos de uso y conllevan diferentes perfiles de riesgo.

Instalación

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"
      }
    }
  }
}

¿No sabes la IP de tu dispositivo?

Solo pregúntale a la IA:

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

Escaneará tu red, probará la conectividad y generará la configuración por ti.

Requisitos

Dispositivo Victron GX en tu red local (Ekrano, Cerbo, Venus GX, etc.)
MQTT (habilitado por defecto en Venus OS) o Modbus TCP (Settings → Services → Modbus TCP)
Node.js 18+

Qué puedes hacer

Informes de energía

Prompt	Qué hace
`hourly-snapshot`	Instantánea rápida del flujo de energía — SOC, PV, red, carga
`daily-report`	Producción, consumo, ratio de autoconsumo, dependencia de la red
`weekly-review`	Tendencias de rendimiento, salud de la batería, patrones de carga, consejos de programación
`monthly-analysis`	Balance energético, ahorro de costes, envejecimiento de la batería, comparación estacional

Optimización energética

Prompt	Qué hace
`energy-optimizer`	Ajuste impulsado por IA — elige objetivo: autoconsumo, ahorro de costes, longevidad de la batería, preparación de respaldo o equilibrado
`ess-tuning`	Revisa el modo ESS, el setpoint de red, los límites de batería, Dynamic ESS
`storm-prep`	Verificación de preparación previa a un corte de suministro

Monitorización y resolución de problemas

Prompt	Qué hace
`diagnose-system`	Chequeo completo de salud con escaneo de alarmas
`solar-performance`	Análisis de rendimiento PV, comparación de trackers, detección de sombreado
`troubleshoot`	Depuración guiada con búsqueda de códigos de error
`tank-monitor`	Niveles de combustible, agua, residuos (marino/RV/off-grid)
`generator-management`	Condiciones de arranque automático, tiempo de funcionamiento, horas de silencio

Descubrimiento de dispositivos

Prompt	Qué hace
`setup-guide`	Asistente de configuración inicial
`find-devices`	Escanea la red, descubre todos los dispositivos GX y sus dispositivos conectados
`identify-device`	"¿Qué es el unit ID 247?" — identifica cualquier dispositivo
`system-topology`	Mapea buses AC/DC, conexiones, rutas de flujo de energía
`device-inventory`	Tabla completa de dispositivos para documentación o soporte
`register-explorer`	Navega por los registros, explica tipos y factores de escala
`firmware-check`	Versiones de firmware en todos los dispositivos

Para instaladores

Prompt	Qué hace
`commissioning`	Lista de verificación de sistema nuevo — inventario, cableado, configuración, aprobado/fallido
`site-audit`	Auditoría de comunicación, alarmas, mediciones, rendimiento

Integración

Prompt	Qué hace
`nodered-check`	Node-RED en Venus OS — topics MQTT, depuración de flujos
`mqtt-debug`	Conectividad del broker, trazado de topics, depuración de keepalive

Referencia de herramientas

Monitorización principal (9 herramientas)

Herramienta	Descripción
`victron_system_overview`	SOC de batería, potencia PV, potencia de red, consumo AC, estado ESS
`victron_battery_status`	SOC, voltaje, corriente, potencia, temperatura, datos de celdas, tiempo restante
`victron_solar_status`	Potencia PV, rendimiento hoy/ayer/total, estado del cargador, datos del tracker
`victron_grid_status`	Potencia de red por fase (L1/L2/L3), voltaje, corriente, frecuencia
`victron_vebus_status`	Multi/Quattro: AC entrada/salida, límite de corriente, modo, estado, alarmas
`victron_tank_levels`	Nivel de tanque, capacidad, restante, tipo de fluido
`victron_temperature`	Temperatura, tipo de sensor, humedad, presión
`victron_inverter_status`	Inversor independiente: salida AC, estado, alarmas
`victron_evcs_status`	Estación de carga EV: potencia, estado, energía de sesión

Dispositivos extendidos (14 herramientas)

Herramienta	Descripción
`victron_multi_status`	Inversor/cargador Multi RS
`victron_pvinverter_status`	Inversores PV acoplados a AC (Fronius, SolarEdge, ABB)
`victron_genset_status`	Controladores de generador AC
`victron_dcgenset_status`	Generadores DC
`victron_alternator_status`	Alternadores NMEA 2000
`victron_charger_status`	Cargadores AC (Skylla, Blue Smart)
`victron_dcdc_status`	Convertidor DC-DC Orion XS
`victron_acload_status`	Sensores de carga AC / corriente
`victron_dcenergy_status`	Medidores de energía DC (SmartShunts en modo medidor DC)
`victron_gx_info`	Identidad del dispositivo GX, estados de relé
`victron_digital_inputs`	Estado y tipo de entrada digital
`victron_gps_status`	Posición GPS, altitud, velocidad
`victron_meteo_status`	Irradiancia solar, velocidad del viento, temperaturas
`victron_generator_status`	Arranque/parada automática del generador, tiempo de funcionamiento, alarmas

Descubrimiento y configuración (4 herramientas)

Herramienta	Descripción
`victron_network_scan`	Escanea la red local para encontrar dispositivos GX
`victron_setup`	Configuración completa: prueba transportes, descubre dispositivos, genera configuración
`victron_mqtt_discover`	Auto-descubre el portal ID MQTT, servicios, instancias de dispositivos
`victron_discover`	Escanea unit IDs Modbus para encontrar dispositivos conectados

Utilidades y documentación (5 herramientas)

Herramienta	Descripción
`victron_read_category`	Lee todos los registros de cualquier categoría de dispositivo
`victron_read_register`	Lee registro(s) crudo(s) por dirección (solo Modbus)
`victron_list_registers`	Lista los registros disponibles para una categoría de dispositivo
`victron_search_docs`	Busca en la documentación offline (registros + API VRM)
`victron_check_online`	Obtén URLs de la documentación más reciente de Victron

Recursos

URI	Contenido
`victron://register-list`	Lista de registros Modbus TCP CCGX (Rev 3.71) — 943 registros
`victron://unit-id-mapping`	Mapeo de tipo de dispositivo a unit ID

Configuración

Variables de entorno

Todas opcionales. Configúralas para evitar repetir parámetros en cada llamada de herramienta.

Variable	Predeterminado	Descripción
`VICTRON_HOST`	(ninguno)	IP o hostname del dispositivo GX
`VICTRON_TRANSPORT`	`modbus`	`modbus` o `mqtt`
`VICTRON_PORTAL_ID`	(auto)	Portal ID para MQTT
`VICTRON_MODBUS_PORT`	`502`	Puerto Modbus TCP
`VICTRON_MQTT_PORT`	`1883`	Puerto del broker MQTT
`VICTRON_UNIT_ID`	`100`	Unit ID Modbus predeterminado

Uso remoto (MCP Connector API)

Este paquete habla stdio, que la Anthropic MCP Connector API no puede alcanzar directamente (Connector necesita HTTPS). Para acceso remoto respaldado por nube, usa el paquete hermano victron-vrm-mcp.

Si realmente necesitas que la Connector API alcance este paquete (p. ej. para usar lecturas de registros crudos de forma remota), tendrías que ponerlo detrás de tu propio gateway HTTPS que hable Streamable HTTP upstream y lance victron-tcp downstream — no recomendado para uso típico.

Depuración

El MCP Inspector es la forma más rápida de interactuar con el servidor de forma interactiva.

# Inspect a locally-built server
npm run inspect

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

Ambos abren una interfaz basada en navegador donde puedes llamar herramientas, ver contenido estructurado y observar el flujo de notificaciones. Los logs van a stderr (stdout está reservado para el flujo JSON-RPC en transporte stdio — nunca escribas a stdout).

Para Claude Desktop específicamente, los logs del servidor MCP se guardan en ~/Library/Logs/Claude/mcp-server-victron-tcp.log (macOS) o %APPDATA%\Claude\logs\mcp-server-victron-tcp.log (Windows). Consulta la guía de depuración de la especificación para un recorrido completo.

Documentación

Guía	Contenido
Setup	Configuraciones de cliente, comparación de transportes, unit IDs, dispositivos soportados
Examples	Prompts del mundo real con comportamiento paso a paso de la IA
Troubleshooting	Errores comunes y soluciones
FAQ	Preguntas frecuentes
Architecture	Estructura del código, mapa de registros, cómo funciona
Security	Modelo de seguridad, sensibilidad de datos, exposición de red

Hoja de ruta

Soporte de escritura — control de modo ESS, setpoint de red, límites de corriente de carga, control de relés (vía topics MQTT W/)
MCP Resources — lista de registros + mapeo de unit ID (especificación VRM API movida a victron-vrm-mcp)
MCP Prompts — 23 flujos de trabajo guiados
Paquete NPM (npx victron-tcp)
Paquete hermano para acceso a nube VRM — victron-vrm-mcp

Referencias

Licencia

MIT