Mcp Server For Victron Energy Gx Devices

Victron TCP — MCP サーバー

AI アシスタントをVictron Energyシステムに接続します。クラウド不要で、ローカルネットワークから太陽光発電、バッテリー、系統電力、インバーターのリアルタイムデータを読み取ります。

32 個のツール | 23 個のプロンプト | 2 個のリソース | 900 以上のレジスター | Modbus TCP + MQTT

---

どのパッケージを選べばよいですか？

これはペアのうちローカル／LAN側です。リモート／クラウド側は**victron-vrm-mcp**です。

	victron-tcp（このリポジトリ）	victron-vrm-mcp
トランスポート	stdio（ローカルサブプロセス）	Streamable HTTP（リモート）
データソース	LAN 上の Modbus TCP + MQTT	VRM クラウド API
LAN 上の GX へのアクセスが必要	はい	いいえ
船や家を離れているときも動作	いいえ	はい
インターネットが停止しているときも動作	はい	いいえ
レイテンシ	リアルタイム（約 50 ms）	約 15 分（VRM のサンプリング間隔）
レジスターへの直接アクセス	はい（900 以上のレジスター）	いいえ
書き込み対応範囲（予定）	幅広い — D-Bus が公開するすべて	限定的 — VRM がリモート操作を許可するもののみ（Dynamic ESS、アラームのクリア、タグなど）
MCP Connector API との互換性	いいえ（stdio）	はい（HTTPS）
クライアント	Claude Code、Claude Desktop、Cursor、Windsurf	Anthropic Messages API + HTTP 経由で MCP に対応するすべてのもの
認証	ローカルでは不要（LAN を信頼）	リクエストごとの VRM 個人アクセストークン

次の場合にこのパッケージを使用してください： GX デバイスと同じ LAN 上にいて、レジスターへの直接アクセスに対応したリアルタイムの低レイテンシ読み取りを利用したい場合。 次の場合は victron-vrm-mcp を使用してください： リモートアクセスが必要な場合、MCP Connector 経由で API 対応アプリを構築する場合、または LAN 上のものを外部に公開したくない場合。

両方を同時に使用できます。それぞれ異なる用途に対応し、リスク特性も異なります。

---

インストール

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

デバイスの IP アドレスがわからない場合

AI に尋ねるだけです。

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

ネットワークをスキャンして接続をテストし、設定を生成します。

要件

• ローカルネットワーク上の Victron GX デバイス（Ekrano、Cerbo、Venus GX など）
• MQTT（Venus OS ではデフォルトで有効）または Modbus TCP（Settings → Services → Modbus TCP）
• Node.js 18+

---

できること

エネルギーレポート

プロンプト	機能
hourly-snapshot	電力フローの簡易スナップショット — SOC、PV、系統電力、負荷
daily-report	発電量、消費量、自家消費率、系統電力への依存度
weekly-review	発電量の傾向、バッテリーの状態、負荷パターン、スケジュールのヒント
monthly-analysis	エネルギーバランス、コスト削減額、バッテリーの経年劣化、季節ごとの比較

エネルギーの最適化

プロンプト	機能
energy-optimizer	AI による調整 — 自家消費、コスト削減、バッテリーの長寿命化、バックアップへの備え、バランスのいずれかを目標として選択
ess-tuning	ESS モード、系統電力の設定値、バッテリーの上限、Dynamic ESS を確認
storm-prep	停電前の準備状況を確認

監視とトラブルシューティング

プロンプト	機能
diagnose-system	アラームスキャンを含む総合ヘルスチェック
solar-performance	PV 発電量の分析、トラッカーの比較、日陰の検出
troubleshoot	エラーコードの照会を含む、ガイド付きのデバッグ
tank-monitor	燃料、水、廃水の残量（船舶／RV／オフグリッド）
generator-management	自動起動条件、稼働時間、静音時間

デバイスの検出

プロンプト	機能
setup-guide	初回セットアップウィザード
find-devices	ネットワークをスキャンし、すべての GX デバイスと接続機器を検出
identify-device	「ユニット ID 247 は何ですか？」— 任意のデバイスを特定
system-topology	AC／DC バス、接続、エネルギーフロー経路をマッピング
device-inventory	ドキュメント作成やサポート用の全デバイス一覧
register-explorer	レジスターを閲覧し、型とスケール係数を説明
firmware-check	すべてのデバイスのファームウェアバージョン

インストーラー向け

プロンプト	機能
commissioning	新規システムのチェックリスト — 機器一覧、配線、設定、合否判定
site-audit	通信、アラーム、測定値、性能の監査

統合

プロンプト	機能
nodered-check	Venus OS 上の Node-RED — MQTT トピック、フローのデバッグ
mqtt-debug	ブローカーへの接続、トピックの追跡、キープアライブのデバッグ

---

ツール一覧

コア監視（9 ツール）

ツール	説明
victron_system_overview	バッテリーの SOC、PV 電力、系統電力、AC 消費電力、ESS の状態
victron_battery_status	SOC、電圧、電流、電力、温度、セルデータ、残り時間
victron_solar_status	PV 電力、今日／昨日／累計の発電量、充電器の状態、トラッカーデータ
victron_grid_status	相ごとの系統電力（L1／L2／L3）、電圧、電流、周波数
victron_vebus_status	Multi／Quattro：AC 入出力、電流制限、モード、状態、アラーム
victron_tank_levels	タンクの水位、容量、残量、液体の種類
victron_temperature	温度、センサーの種類、湿度、気圧
victron_inverter_status	単独型インバーター：AC 出力、状態、アラーム
victron_evcs_status	EV 充電ステーション：電力、状態、セッションのエネルギー量

拡張デバイス（14 ツール）

ツール	説明
victron_multi_status	Multi RS インバーター／チャージャー
victron_pvinverter_status	AC 結合型 PV インバーター（Fronius、SolarEdge、ABB）
victron_genset_status	AC 発電機コントローラー
victron_dcgenset_status	DC 発電機
victron_alternator_status	NMEA 2000 オルタネーター
victron_charger_status	AC 充電器（Skylla、Blue Smart）
victron_dcdc_status	Orion XS DC-DC コンバーター
victron_acload_status	AC 負荷／電流センサー
victron_dcenergy_status	DC エネルギーメーター（DC メーターモードの SmartShunt）
victron_gx_info	GX デバイスの識別情報、リレーの状態
victron_digital_inputs	デジタル入力の状態と種類
victron_gps_status	GPS の位置、高度、速度
victron_meteo_status	日射量、風速、温度
victron_generator_status	発電機の自動起動／停止、稼働時間、アラーム

検出とセットアップ（4 ツール）

ツール	説明
victron_network_scan	ローカルネットワークをスキャンして GX デバイスを検出
victron_setup	完全なセットアップ：トランスポートをテストし、デバイスを検出して、設定を生成
victron_mqtt_discover	MQTT ポータル ID、サービス、デバイスインスタンスを自動検出
victron_discover	Modbus のユニット ID をスキャンして接続済みデバイスを検出

ユーティリティとドキュメント（5 ツール）

ツール	説明
victron_read_category	任意のデバイスカテゴリの全レジスターを読み取る
victron_read_register	アドレスでレジスター（複数可）の生データを読み取る（Modbus のみ）
victron_list_registers	デバイスカテゴリで使用可能なレジスターを一覧表示
victron_search_docs	オフラインドキュメント（レジスターと VRM API）を検索
victron_check_online	最新の Victron ドキュメントの URL を取得

リソース

URI	内容
victron://register-list	CCGX Modbus TCP レジスター一覧（Rev 3.71）— 943 レジスター
victron://unit-id-mapping	デバイスの種類とユニット ID の対応表

---

設定

環境変数

すべて任意です。各ツール呼び出しのたびにパラメーターを繰り返し指定しなくて済むよう、設定してください。

変数	デフォルト値	説明
VICTRON_HOST	(none)	GX デバイスの IP アドレスまたはホスト名
VICTRON_TRANSPORT	modbus	modbus または mqtt
VICTRON_PORTAL_ID	(auto)	MQTT 用のポータル ID
VICTRON_MODBUS_PORT	502	Modbus TCP ポート
VICTRON_MQTT_PORT	1883	MQTT ブローカーポート
VICTRON_UNIT_ID	100	デフォルトの Modbus ユニット ID

リモートでの使用（MCP Connector API）

このパッケージは stdio を使用するため、Anthropic MCP Connector API から直接アクセスできません（Connector には HTTPS が必要です）。クラウド経由でリモートアクセスする場合は、姉妹パッケージの victron-vrm-mcp を使用してください。

Connector API からこのパッケージにアクセスする必要がある場合（たとえば、生のレジスター読み取りをリモートで行う場合）は、Streamable HTTP を上流で受け付け、victron-tcp を下流で起動する独自の HTTPS ゲートウェイの背後に配置します。ただし、一般的な用途にはおすすめしません。

---

デバッグ

MCP Inspector を使うと、サーバーを対話的に試すことができます。

# Inspect a locally-built server
npm run inspect

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

どちらもブラウザベースの UI を開き、ツールの呼び出しや構造化コンテンツの表示、通知ストリームの確認ができます。ログは stderr に出力されます（stdout は stdio トランスポートでの JSON-RPC ストリーム用に予約されているため、stdout には決して書き込まないでください）。

特に Claude Desktop の場合、MCP サーバーのログは ~/Library/Logs/Claude/mcp-server-victron-tcp.log（macOS）または %APPDATA%\Claude\logs\mcp-server-victron-tcp.log（Windows）に保存されます。詳しい手順については、仕様のデバッグガイドをご覧ください。

---

ドキュメント

ガイド	内容
セットアップ	クライアント設定、トランスポートの比較、ユニット ID、対応デバイス
例	実際のプロンプトと、段階ごとの AI の動作
トラブルシューティング	よくあるエラーと解決方法
FAQ	よくある質問
アーキテクチャ	コード構造、レジスターマップ、仕組み
セキュリティ	セキュリティモデル、データの機密性、ネットワークへの公開

---

ロードマップ

• 書き込み対応 — ESS モード制御、グリッド設定値、充電電流の上限、リレー制御（MQTT の W/ トピック経由）
• MCP リソース — レジスター一覧とユニット ID のマッピング（VRM API 仕様は victron-vrm-mcp に移動しました）
• MCP プロンプト — 23 のガイド付きワークフロー
• NPM パッケージ（npx victron-tcp）
• VRM クラウドアクセス用の姉妹パッケージ — victron-vrm-mcp

参考資料

• Victron Modbus TCP FAQ
• CCGX Register List (Excel)
• Venus OS | MQTT ドキュメント
• VRM API | MCP Protocol

ライセンス

MIT