Victron ModBus TCP

Servidor que se conecta a dispositivos Victron Energy GX na rede local.

Documentação

Victron TCP — MCP Server

Conecte assistentes de IA a sistemas Victron Energy. Leia dados em tempo real de solar, bateria, rede elétrica e inversores da sua rede local — sem necessidade de nuvem.

32 ferramentas | 23 prompts | 2 recursos | 900+ registradores | Modbus TCP + MQTT

Qual pacote eu quero?

Esta é a metade local / LAN de um par. A metade remota / nuvem é victron-vrm-mcp.

	`victron-tcp` (este repositório)	`victron-vrm-mcp`
Transporte	stdio (subprocesso local)	Streamable HTTP (remoto)
Fonte de dados	Modbus TCP + MQTT na sua LAN	API de nuvem VRM
Precisa de acesso ao GX na sua LAN	Sim	Não
Funciona quando você está longe do barco / casa	Não	Sim
Funciona quando a internet cai	Sim	Não
Latência	Tempo real (~50 ms)	~15 min (amostragem VRM)
Acesso bruto a registradores	Sim (900+ registradores)	Não
Cobertura de escrita (planejada)	Ampla — tudo o que o D-Bus expõe	Estreita — apenas o que o VRM permite remotamente (Dynamic ESS, clear-alarm, tags, …)
Compatível com API MCP Connector	Não (stdio)	Sim (HTTPS)
Clientes	Claude Code, Claude Desktop, Cursor, Windsurf	Anthropic Messages API + qualquer coisa que fale MCP via HTTP
Autenticação	Nenhuma localmente (confia na LAN)	Token de acesso pessoal VRM por solicitação

Use este pacote quando: você estiver na mesma LAN que um dispositivo GX e quiser acesso de leitura em tempo real, de baixa latência, com suporte a registradores brutos. Use victron-vrm-mcp quando: você precisar de acesso remoto, estiver criando um aplicativo com API via MCP Connector, ou não quiser expor nada na sua LAN.

Você pode usar ambos simultaneamente — eles atendem a casos de uso diferentes e têm perfis de risco diferentes.

Instalação

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

Não sabe o IP do seu dispositivo?

Basta perguntar à IA:

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

Ela fará a varredura da sua rede, testará a conectividade e gerará a configuração para você.

Requisitos

Dispositivo Victron GX na sua rede local (Ekrano, Cerbo, Venus GX, etc.)
MQTT (habilitado por padrão no Venus OS) ou Modbus TCP (Configurações → Serviços → Modbus TCP)
Node.js 18+

O que você pode fazer

Relatórios de Energia

Prompt	O que faz
`hourly-snapshot`	Instantâneo rápido do fluxo de energia — SOC, PV, rede, carga
`daily-report`	Produção, consumo, taxa de autoconsumo, dependência da rede
`weekly-review`	Tendências de rendimento, saúde da bateria, padrões de carga, dicas de agendamento
`monthly-analysis`	Balanço de energia, economia de custos, envelhecimento da bateria, comparação sazonal

Otimização de Energia

Prompt	O que faz
`energy-optimizer`	Ajuste orientado por IA — escolha o objetivo: autoconsumo, economia de custos, longevidade da bateria, prontidão de backup ou equilibrado
`ess-tuning`	Revise o modo ESS, setpoint da rede, limites da bateria, Dynamic ESS
`storm-prep`	Verificação de prontidão antes de queda de energia

Monitoramento e Solução de Problemas

Prompt	O que faz
`diagnose-system`	Verificação completa de saúde com varredura de alarmes
`solar-performance`	Análise de rendimento PV, comparação de rastreadores, detecção de sombreamento
`troubleshoot`	Depuração guiada com consulta de códigos de erro
`tank-monitor`	Níveis de combustível, água, resíduos (marinho/RV/off-grid)
`generator-management`	Condições de partida automática, tempo de execução, horários silenciosos

Descoberta de Dispositivos

Prompt	O que faz
`setup-guide`	Assistente de configuração inicial
`find-devices`	Varra a rede, descubra todos os dispositivos GX e seus dispositivos conectados
`identify-device`	"O que é o unit ID 247?" — identifique qualquer dispositivo
`system-topology`	Mapeie barramentos AC/DC, conexões, caminhos de fluxo de energia
`device-inventory`	Tabela completa de dispositivos para documentação ou suporte
`register-explorer`	Navegue pelos registradores, explique tipos e fatores de escala
`firmware-check`	Versões de firmware em todos os dispositivos

Para Instaladores

Prompt	O que faz
`commissioning`	Checklist de sistema novo — inventário, cabeamento, configuração, aprovado/reprovado
`site-audit`	Comunicação, alarmes, medições, auditoria de desempenho

Integração

Prompt	O que faz
`nodered-check`	Node-RED no Venus OS — tópicos MQTT, depuração de fluxos
`mqtt-debug`	Conectividade do broker, rastreamento de tópicos, depuração de keepalive

Referência de Ferramentas

Monitoramento Principal (9 ferramentas)

Ferramenta	Descrição
`victron_system_overview`	SOC da bateria, potência PV, potência da rede, consumo AC, status do ESS
`victron_battery_status`	SOC, tensão, corrente, potência, temperatura, dados das células, tempo restante
`victron_solar_status`	Potência PV, rendimento hoje/ontem/total, estado do carregador, dados do rastreador
`victron_grid_status`	Potência da rede por fase (L1/L2/L3), tensão, corrente, frequência
`victron_vebus_status`	Multi/Quattro: AC entrada/saída, limite de corrente, modo, estado, alarmes
`victron_tank_levels`	Nível do tanque, capacidade, restante, tipo de fluido
`victron_temperature`	Temperatura, tipo de sensor, umidade, pressão
`victron_inverter_status`	Inversor autônomo: saída AC, estado, alarmes
`victron_evcs_status`	Estação de carregamento EV: potência, status, energia da sessão

Dispositivos Estendidos (14 ferramentas)

Ferramenta	Descrição
`victron_multi_status`	Inversor/carregador Multi RS
`victron_pvinverter_status`	Inversores PV acoplados em AC (Fronius, SolarEdge, ABB)
`victron_genset_status`	Controladores de gerador AC
`victron_dcgenset_status`	Geradores DC
`victron_alternator_status`	Alternadores NMEA 2000
`victron_charger_status`	Carregadores AC (Skylla, Blue Smart)
`victron_dcdc_status`	Conversor DC-DC Orion XS
`victron_acload_status`	Sensores de carga / corrente AC
`victron_dcenergy_status`	Medidores de energia DC (SmartShunts no modo medidor DC)
`victron_gx_info`	Identidade do dispositivo GX, estados dos relés
`victron_digital_inputs`	Estado e tipo da entrada digital
`victron_gps_status`	Posição GPS, altitude, velocidade
`victron_meteo_status`	Irradiância solar, velocidade do vento, temperaturas
`victron_generator_status`	Partida/parada automática do gerador, tempo de execução, alarmes

Descoberta e Configuração (4 ferramentas)

Ferramenta	Descrição
`victron_network_scan`	Varra a rede local para encontrar dispositivos GX
`victron_setup`	Configuração completa: teste transportes, descubra dispositivos, gere configuração
`victron_mqtt_discover`	Descubra automaticamente o portal ID MQTT, serviços, instâncias de dispositivos
`victron_discover`	Varra os unit IDs Modbus para encontrar dispositivos conectados

Utilitários e Documentação (5 ferramentas)

Ferramenta	Descrição
`victron_read_category`	Leia todos os registradores de qualquer categoria de dispositivo
`victron_read_register`	Leia registrador(es) bruto(s) por endereço (somente Modbus)
`victron_list_registers`	Liste os registradores disponíveis para uma categoria de dispositivo
`victron_search_docs`	Pesquise na documentação offline (registradores + API VRM)
`victron_check_online`	Obtenha URLs da documentação mais recente da Victron

Recursos

URI	Conteúdo
`victron://register-list`	Lista de registradores Modbus TCP CCGX (Rev 3.71) — 943 registradores
`victron://unit-id-mapping`	Mapeamento de tipo de dispositivo para unit ID

Configuração

Variáveis de Ambiente

Todas opcionais. Defina-as para evitar repetir parâmetros em cada chamada de ferramenta.

Variável	Padrão	Descrição
`VICTRON_HOST`	(nenhum)	IP ou hostname do dispositivo GX
`VICTRON_TRANSPORT`	`modbus`	`modbus` ou `mqtt`
`VICTRON_PORTAL_ID`	(automático)	Portal ID para MQTT
`VICTRON_MODBUS_PORT`	`502`	Porta Modbus TCP
`VICTRON_MQTT_PORT`	`1883`	Porta do broker MQTT
`VICTRON_UNIT_ID`	`100`	Unit ID Modbus padrão

Uso remoto (API MCP Connector)

Este pacote fala stdio, que a API Anthropic MCP Connector não consegue acessar diretamente (o Connector precisa de HTTPS). Para acesso remoto via nuvem, use o pacote irmão victron-vrm-mcp.

Se você realmente precisar que a API Connector acesse este pacote (por exemplo, para usar leituras brutas de registradores remotamente), você precisaria colocá-lo atrás do seu próprio gateway HTTPS que fale Streamable HTTP upstream e execute victron-tcp downstream — não recomendado para uso típico.

Depuração

O MCP Inspector é a forma mais rápida de interagir com o servidor.

# Inspect a locally-built server
npm run inspect

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

Ambos abrem uma interface baseada em navegador onde você pode chamar ferramentas, visualizar conteúdo estruturado e acompanhar o fluxo de notificações. Os logs vão para stderr (stdout é reservado para o fluxo JSON-RPC no transporte stdio — nunca escreva em stdout).

Especificamente para o Claude Desktop, os logs do servidor MCP ficam em ~/Library/Logs/Claude/mcp-server-victron-tcp.log (macOS) ou %APPDATA%\Claude\logs\mcp-server-victron-tcp.log (Windows). Consulte o guia de depuração da especificação para um passo a passo completo.

Documentação

Guia	Conteúdo
Setup	Configurações de cliente, comparação de transportes, unit IDs, dispositivos suportados
Examples	Prompts reais com comportamento passo a passo da IA
Troubleshooting	Erros comuns e correções
FAQ	Perguntas frequentes
Architecture	Estrutura do código, mapa de registradores, como funciona
Security	Modelo de segurança, sensibilidade dos dados, exposição na rede

Roadmap

Suporte a escrita — controle do modo ESS, setpoint da rede, limites de corrente de carga, controle de relés (via tópicos MQTT W/)
Recursos MCP — lista de registradores + mapeamento de unit ID (especificação da API VRM movida para victron-vrm-mcp)
Prompts MCP — 23 fluxos de trabalho guiados
Pacote NPM (npx victron-tcp)
Pacote irmão para acesso à nuvem VRM — victron-vrm-mcp

Referências

Licença

MIT