Victron Vrm Mcp — Mcp Server

Victron VRM MCP — MCP サーバー

Victron Energy の VRM クラウド API 用 MCP サーバーです。Streamable HTTP 経由で 53 個の VRM ツールを提供します。Anthropic MCP Connector API と、HTTP 対応のあらゆる MCP クライアントですぐに利用できます。

53 個のツール | Streamable HTTP | セキュリティ優先 | 506 件のテスト（オフライン 415 件 + ライブ 91 件）| MCP Connector 対応

---

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

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

	victron-tcp	victron-vrm-mcp（このリポジトリ）
トランスポート	stdio（ローカルサブプロセス）	Streamable HTTP（リモート）
データソース	LAN 上の Modbus TCP + MQTT	VRM クラウド API
LAN 上の GX へのアクセスが必要	はい	いいえ
ボート／家から離れているときも動作	いいえ	はい
インターネットがダウンしていても動作	はい	いいえ
レイテンシー	リアルタイム（約 50 ms）	約 15 分（VRM のサンプリング間隔）
レジスターへの直接アクセス	はい（900 個以上のレジスター）	いいえ
書き込み対応範囲	現在は読み取り専用。MQTT 経由の書き込みを予定	破壊的な操作を行うツールが 24 個。すべて confirm による確認が必要
MCP Connector API との互換性	いいえ（stdio）	はい（HTTPS）
クライアント	Claude Code、Claude Desktop、Cursor、Windsurf	Anthropic Messages API + HTTP 経由で MCP を利用するあらゆるクライアント
認証	ローカルでは不要（LAN を信頼）	リクエストごとの VRM 個人アクセストークン

victron-tcp を使う場合： GX デバイスと同じ LAN 上にいて、レジスターへの直接アクセスを含むリアルタイムアクセスが必要な場合。 victron-vrm-mcp を使う場合： リモートアクセスが必要な場合、MCP Connector を介して API ベースのアプリを構築する場合、または LAN 上のものを外部に公開したくない場合。

両方を同時に使うこともできます。それぞれ異なる用途に対応します。

---

インストール

victron-tcp とは異なり、このパッケージはセルフホストするサーバーであり、クライアントが起動するプロセスではありません。一度実行して、その前段に HTTPS を設定し、MCP クライアントを URL に接続します。

npm から実行（推奨）

# one-off (no install)
npx victron-vrm-mcp

# or install globally
npm install -g victron-vrm-mcp
victron-vrm-mcp

# or pin in a project
npm install victron-vrm-mcp
npx victron-vrm-mcp

デフォルトでは http://127.0.0.1:3000/mcp で待ち受けます。環境変数（PORT、HOST、ALLOWED_ORIGINS、VRM_ALLOWED_SITES、VRM_AUTH_SCHEME）で設定できます。詳しくは .env.example を参照してください。

ソースから実行（開発用）

git clone https://github.com/lubosstrejcek/victron-vrm-mcp.git
cd victron-vrm-mcp
npm install
npm run build
npm start

デフォルトのバインド先は同じです（http://127.0.0.1:3000/mcp）。

Docker

Dockerfile は今後追加する予定です。現時点では、必要に応じて調整できる最小限のワンライナーを示します。

docker run --rm -it -p 3000:3000 -e HOST=0.0.0.0 \
  -e ALLOWED_ORIGINS="https://claude.ai" \
  node:22-alpine sh -c "npx -y victron-vrm-mcp"

パブリック HTTPS（推奨）

リモートクライアントには実際の TLS が必要です。ファイアウォールのポートを開放せずに済む最も簡単な方法は、Cloudflare Tunnel です。

cloudflared tunnel create vrm
cloudflared tunnel route dns vrm victron-vrm.example.com
cloudflared tunnel run --url http://127.0.0.1:3000 vrm

これで https://victron-vrm.example.com/mcp は、有効な証明書を使って、ポートを開放せずにアクセスできるようになります。ほかの方法として、nginx／Caddy リバースプロキシ、Fly.io、Cloudflare Workers アダプター（今後追加予定）があります。

Anthropic Messages API（MCP Connector）

{
  "mcp_servers": [{
    "type": "url",
    "url": "https://victron-vrm.example.com/mcp",
    "name": "victron-vrm",
    "authorization_token": "<your-vrm-personal-access-token>"
  }],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "victron-vrm" }]
}

Claude Code／Cursor／Windsurf（HTTP トランスポート）

claude mcp add-json victron-vrm '{"type":"http","url":"https://victron-vrm.example.com/mcp","headers":{"Authorization":"Bearer YOUR_VRM_TOKEN"}}'

VRM トークンがわからない場合

VRM → Preferences → Integrations → Access tokens で個人アクセストークンを作成してください（エンドポイント：POST /users/{idUser}/accesstokens/create）。アクセストークンは有効期間が長く、取り消し可能で、今後サードパーティー認証に使用する正式な方法です。

⚠️ VRM Bearer トークン（/auth/login、/auth/loginAsDemo）は 2026-06-01 以降非推奨です（公式 OpenAPI 仕様に記載済み）。このサーバーではテスト用に x-vrm-auth-scheme: Bearer で引き続き使用できますが、新しい連携ではアクセストークンを必ず使用してください。Bearer スキームを使用するたびに警告がログに記録されます。

アクセストークンを取得する前に簡単な動作確認をする場合は、GET https://vrmapi.victronenergy.com/v2/auth/loginAsDemo を呼び出すと、Victron のデモテナントで使用できる有効期間の短い Bearer トークンが返されます。

idSite がわからない場合

まず vrm_list_installations を呼び出してください。トークンでアクセスできるすべてのサイトが返されます。または、12 文字のポータル ID をお持ちの場合は、vrm_get_site_id を呼び出して解決できます。

要件

• Node.js 22.11+（サポート対象の2つのLTS系列、22と24）
• VRM パーソナルアクセストークン（テスト用のデモログイン Bearer も使用できます）
• MCP Connector API からアクセスさせる場合は、パブリック HTTPS

---

ツール

88以上の VRM 操作をカバーする53個のツール（直接操作53個 + 汎用 vrm_widget ディスパッチャー経由のウィジェットエンドポイント35個以上）。破壊的な操作を行うツールはすべて confirm: true で保護され、各ツールで inputSchema、outputSchema、MCP アノテーションが宣言されています。

検出と検索（4ツール）

ツール	説明
vrm_list_installations	トークンがアクセスできるすべてのサイトを一覧表示します（Markdown の切り詰めには limit を使用できます）
vrm_search_sites	サイト ID、メールアドレス、ユーザー名、シリアル番号、サイト識別子、メールドメインで検索します
vrm_get_site_id	12文字のポータル ID を数値の idSite に解決します
vrm_list_invites	ユーザーが送受信した招待を一覧表示します

モニタリング — 読み取り（11ツール）

ツール	説明
vrm_get_system_overview	サイトに接続されているデバイスとロール
vrm_get_diagnostics	デバイスごとの直近の属性値
vrm_get_stats	時系列統計（15分／時間／日／週／月／年）
vrm_get_overallstats	全期間の集計統計
vrm_get_alarms	設定済みアラーム、デバイス、通知ユーザー、利用可能な属性
vrm_get_site_users	サイトのユーザー、招待、アクセスリクエスト、グループリンク
vrm_get_tags	ソース（ユーザー／チーム／グループ／定義済み）別に分類したタグ
vrm_get_dynamic_ess_settings	現在の Dynamic ESS 設定
vrm_get_gps_download	GPS 位置履歴
vrm_get_forecasts_last_reset	予測を最後にリセットしたタイムスタンプ（未実施の場合は0）
vrm_get_custom_widgets	サイトに設定されたカスタムウィジェット

ウィジェット（3ツール — 35以上のウィジェットエンドポイントに対応）

ツール	説明
vrm_widget	任意の VRM ウィジェット名に対応する汎用ディスパッチャー（BatterySummary、SolarChargerSummary、TankSummary、VeBusState、MPPTState、InputState、InverterState、PVInverterStatus、MotorSummary、GlobalLinkSummary、MeteorologicalSensorOverview、Status、HoursOfAc、LithiumBMS、DCMeter、FuelCellState、BatteryRelayState、ChargerRelayState、GatewayRelayState、SolarChargerRelayState、BatteryMonitorWarningsAndAlarms、VeBusWarningsAndAlarms、InverterChargerState、InverterChargerWarningsAndAlarms、EssBatteryLifeState、IOExtenderInOut、BMSDiagnostics、HistoricData、TempSummaryAndGraph、TempAirQuality、EvChargerSummary など）
vrm_widget_graph	attributeCodes[]／attributeIds[]、start／end、useMinMax を指定する時系列グラフ
vrm_widget_generator_state	発電機の状態変化タイムライン

書き込み — 低リスク（4ツール、確認必須）

ツール	説明
vrm_set_favorite	サイトをお気に入りに設定／解除します
vrm_tags_add	サイトにタグを追加します
vrm_tags_remove	サイトからタグを削除します
vrm_clear_alarm	アクティブなアラームを確認します

書き込み — 中リスク（5ツール、確認必須）

ツール	説明
vrm_add_alarm	アラームを作成します（浮動小数点数または列挙型のしきい値）
vrm_edit_alarm	既存のアラームを変更します
vrm_delete_alarm	アラーム定義を削除します
vrm_reset_forecasts	サイトの予測ベースラインをリセットします
vrm_set_site_settings	サイト名、メモ、ジオフェンス、アラーム監視、Node-RED の制限などを更新します

書き込み — 影響大（1ツール、確認必須）

ツール	説明
vrm_set_dynamic_ess_settings	Dynamic ESS の設定（スケジュール、b2g、priceSchedule、batteryKwh など）を書き込みます

アクセス管理（8 個のツール、確認が必要）

ツール	説明
vrm_invite_user	アクセスレベル（0＝監視、1＝管理者、2＝技術者）を指定して、メールでユーザーを招待します
vrm_unlink_user	ユーザーをサイトから削除します
vrm_unlink_installation	現在のユーザーをサイトから削除します（自分自身のリンク解除）
vrm_set_user_rights	ユーザーごとのアクセスレベルを一括更新します
vrm_set_invite_rights	保留中の招待のアクセスレベルを一括更新します
vrm_link_user_groups	アクセスレベルを指定してユーザーグループをリンクします
vrm_set_user_group_access_level	ユーザーグループのアクセスレベルを変更または削除します
vrm_add_site	ユーザーアカウントにインストールを追加します

アクセストークン（2 個のツール、確認が必要）

ツール	説明
vrm_create_access_token	有効期間の長い個人用アクセストークンを作成します
vrm_delete_access_token	ID を指定して 1 つのトークンを取り消すか、"*" を指定してすべて取り消します — 自分自身がロックアウトされる可能性があります

認証（3 個のツール — Bearer フロー、2026-06-01 に非推奨）

ツール	説明
vrm_auth_login_as_demo	デモテナント用の短期間有効な Bearer を取得します（読み取り専用）
vrm_auth_login	メールアドレスとパスワードでログインします（非推奨、セキュリティ上の危険あり — アクセストークンを使用してください）
vrm_auth_logout	現在の Bearer セッションを無効にします

カスタムウィジェット CRUD（4 個のツール）

ツール	説明
vrm_get_custom_widgets	サイトのカスタムウィジェットを一覧表示します
vrm_create_custom_widget	作成します（確認が必要）
vrm_patch_custom_widget	更新します（確認が必要）
vrm_delete_custom_widget	削除します（確認が必要）

データ属性（2 個のツール）

ツール	説明
vrm_find_by_data_attributes	属性条件（bs>=50,au=(1,2)）でユーザーのインストールを検索します。サーバー側の page／count ページネーションに対応しています
vrm_list_data_attributes	すべての VRM 属性定義のカタログです

管理／コレクション（6 個のツール — 大半は管理者権限が必要）

ツール	説明
vrm_admin_list_devices	システム全体のすべてのデバイス
vrm_admin_data_attributes_count	データ属性条件に一致するインストール数をカウントします
vrm_admin_search_download	一括検索のエクスポート
vrm_list_firmwares	ファームウェアカタログ（feedChannel と victronConnectVersion が必要）
vrm_add_system	新しいシステムを登録します（確認が必要）
vrm_installation_overview_download	概要を一括エクスポートします（バイナリペイロードを base64 として返します）

リソース

URI	内容
docs/vrm-api-openapi.yaml	参照用にバンドルされた VRM OpenAPI 3.1 仕様（78 個のエンドポイント、2026-04 更新）

---

設定

環境変数

変数	デフォルト	説明
PORT	3000	HTTP ポート
HOST	127.0.0.1	バインドアドレス
MCP_PATH	/mcp	エンドポイントパス
VRM_AUTH_SCHEME	Token	VRM への転送に使用するデフォルトのスキームです。Token（アクセストークン）を使用してください。VRM では Bearer は 2026-06-01 に非推奨となります。リクエストごとの上書きには x-vrm-auth-scheme ヘッダーを使用します。
VRM_ALLOWED_SITES	(未設定)	カンマ区切りの idSite 許可リストです。未設定の場合、トークンでアクセス可能なすべてのサイトが許可されます。
ALLOWED_ORIGINS	(未設定)	許可する Origin ヘッダー値のカンマ区切りリストです。未設定の場合、同一オリジンとループバックのみが許可されます。

ローカルの .env（任意）

.env.example を .env にコピーして調整します。Node 20.6+ では直接読み込まれます。

node --env-file=.env dist/index.js

.env は gitignore 対象です。VRM トークンを .env に記述しないでください — トークンはリクエストごとに Authorization ヘッダーで渡します。

リクエストごとのヘッダー

ヘッダー	目的
Authorization: Bearer <vrm-token>	必須です。 転送する VRM トークンです。
x-vrm-auth-scheme: Token|Bearer	省略可能です。このリクエストに限り VRM_AUTH_SCHEME を上書きします。/auth/loginAsDemo トークンには Bearer を使用してください。
x-vrm-skip-confirms: 1	省略可能です。破壊的なツールに対する confirm: true の条件を回避します。自動化専用です。対話型セッションでは使用しないでください。skip_confirms_enabled 警告として記録されます。
Origin	DNS リバインディング対策として、ALLOWED_ORIGINS（または同一オリジン）に照らして検証されます。
mcp-protocol-version	サポート対象のバージョン（2025-06-18、2025-03-26）に照らして検証されます。

---

セキュリティモデル

レイヤー	動作
Origin ヘッダーの検証	Origin が ALLOWED_ORIGINS に含まれない場合（またはローカル開発環境でホストと一致しない場合）、クロスオリジンリクエストを拒否します。DNS リバインディング対策です。
厳格な Accept と Content-Type	POST には Content-Type: application/json と、application/json および text/event-stream の両方を含む Accept の送信が必要です。シンプルな POST による CSRF も防止します。
MCP-Protocol-Version の許可リスト	このサーバーがサポートするバージョンのみを受け付けます。不明なバージョンには 400 を返します。
Bearer トークンが必須	トークンがない場合や、短すぎると判断された場合は、VRM への呼び出しを行う前に拒否します。
トークンを保存・記録しない	トークンが存在するのは、転送する fetch 呼び出しの間だけです。ロガーは token または authorization を含むキーを自動的に除去します。
Zod による入力検証	すべてのツール引数をスキーマで検証します。idSite／idUser は正の整数である必要があり、ウィジェット名は厳格な PascalCase 正規表現に一致する必要があります。リクエストボディはツールごとにスキーマ検証されます。
URL セーフなパス構築	パスパラメーターは、共通の sitePath()／userPath() ヘルパー内で encodeURIComponent によって URL エンコードされます。URL への文字列テンプレートの埋め込みは行いません。
VRM ベース URL のホスト固定	クライアントは、HTTPS 経由で vrmapi.victronenergy.com 以外への呼び出しを拒否します。
破壊的操作の制限	書き込み／削除を行うツールには { confirm: true } または x-vrm-skip-confirms: 1 ヘッダー（自動化向けの明示的な許可）が必要です。拒否は MCP クライアント側だけでなく、サーバー側で行われます。クライアントが UX 上の確認を強制できるよう、MCP アノテーション（destructiveHint、idempotentHint、readOnlyHint）が設定されています。
省略可能なサイト許可リスト	VRM_ALLOWED_SITES=123,456 を設定すると、サーバーがアクセスできるサイトを指定したセットに制限します。VRM へのアクセス前に拒否されます。
レート制限への対応	429 レスポンスには Retry-After が含まれます。サイレントリトライは行いません。
エラーボディの秘匿化	VRM のエラーボディは error_code: errors-text に置き換えられ、256 文字で切り詰められます。生のレスポンスボディがクライアントに渡されることはありません。
リクエストごとのステートレス処理	リクエストごとに新しい McpServer と StreamableHTTPServerTransport を生成します。リクエスト間で状態を共有せず、セッション認証も行いません。
構造化された JSON の stderr ログ	すべての運用イベントを 1 行の JSON で記録します。トークン／認証関連のキーは除去されます。
DELETE は 405 を返す	サーバーはステートレスであり、削除するセッションがありません。

---

仕組み

┌──────────────────────────┐       HTTPS + Bearer token        ┌──────────────────────┐
│  MCP client              │ ────────────────────────────────▶ │  victron-vrm-mcp     │
│  (Connector API, Claude  │                                    │  (Streamable HTTP)   │
│   Code, Cursor, etc.)    │                                    └──────────┬───────────┘
└──────────────────────────┘                                               │
                                                                           │ x-authorization: Token …
                                                                           ▼
                                                        https://vrmapi.victronenergy.com/v2

サーバーはステートレスです。各 MCP リクエストに独自の VRM トークンが含まれます。リクエストごとに新しい McpServer と StreamableHTTPServerTransport を構築し、SDK の RequestHandlerExtra.authInfo チャネルを通じて認証情報を転送します。

---

デバッグ

MCP Inspector は、サーバーを対話形式で試す最も手早い方法です。

# Terminal 1 — start the server
npm run build && npm start
# (or: PORT=3000 npx victron-vrm-mcp)

# Terminal 2 — launch the Inspector UI
npm run inspect
# Then in the UI:
#   Transport:  Streamable HTTP
#   URL:        http://127.0.0.1:3000/mcp
#   Headers:    Authorization: Bearer <your-vrm-token>
#               x-vrm-auth-scheme: Token   (or Bearer for /auth/loginAsDemo tokens)

ログは stderr に 1 行の JSON として出力されます（Streamable HTTP トランスポートでは stderr の内容はクライアントに転送されません。仕様のデバッグガイドを参照してください）。クライアントから参照できる診断情報には、仕様で notifications/message が用意されています（今後のリリースで追加予定です）。

テスト

16 ファイルにわたる415件のテストを約12秒で実行します。完全にオフラインで動作し、VRMへのネットワーク呼び出しはありません。

npm test           # build + the offline suite
npm run test:unit  # unit tests only (no server spawn)
npm run test:live  # 91 extra tests against VRM's public demo tenant (needs network)

tests/live.test.ts は意図的に vitest.config.ts から除外されており、専用の vitest.live.config.ts を通じてのみ実行されます。そのため、npm test と CI は vrmapi.victronenergy.com の稼働状況に依存しません。認証情報は不要です。テスト内で匿名のデモトークンを発行します。

ファイル	カバレッジ
tests/handlers.test.ts	すべてのツールハンドラーを、スタブ化した VRM に対してプロセス内で実行します。リクエストの構築（メソッド／パス／クエリ／本文）、Markdown と structuredContent の整形、VRM の境界での破壊的操作ゲートの検証、エラーの秘匿、VRM_ALLOWED_SITES の適用をカバーします
tests/helpers.test.ts	zod スキーマ、sitePath／userPath のエンコード、requireConfirm と skip によるバイパス、resolveAuth のトークンガード、formatVrmError による秘匿をカバーします
tests/client.test.ts	トークン長のガード、スキームの転送、配列クエリのエンコード、ホストの固定、4xx → VrmApiError、429 Retry-After、バイナリダウンロードの往復をカバーします
tests/logger.test.ts	token／authorization キーの自動秘匿（大文字・小文字を区別しない）をカバーします
tests/http.test.ts	エンドツーエンドの HTTP：404／405／401／403／406／415／400／200、Origin の検証、確認ゲート、skip ヘッダーをカバーします
tests/tools.coverage.test.ts	53個すべてのツールの正しい形式とアノテーションを確認します。すべての破壊的ツールについて、確認なしでは拒否し、skip ヘッダーがある場合は通過することを検証します
tests/outputSchema.test.ts	すべてのツールが1つ以上のプロパティを持つ outputSchema を宣言していることを確認します。説明文の品質（長さ、エンドポイントへの言及、インジェクションマーカーがないこと、破壊的ツールが危険性を明記していること）も確認します
tests/regressions.test.ts	特定のバグを再発防止するテスト：skip による確認のバイパス、firmwares の必須パラメーター、バイナリダウンロード、パストラバーサルの拒否、ウィジェット名の正規表現、上限値
tests/fuzz.test.ts	不正な JSON、1 MB の本文、Unicode／制御文字／XSS／SQL インジェクション文字列、配列長の上限、Content-Type のエッジケース、トークン漏洩の検出用センチネルをカバーします

CI：.github/workflows/ci.yml は Node 22／24（サポート対象の2つの LTS 系列）で、push と PR のたびにカバレッジしきい値（src/ に対して行80%／分岐72%）を含む全テストを実行します。さらに、トークン漏洩の検出用センチネルの grep と npm audit も実行します。

評価

evals/*.xml — 複数のツールを使う12件のシナリオ評価です（CIでは実行せず、LLM クライアントを使って手動で採点します）。検出と概要、バッテリーの直近1時間の状況、アラームのトリアージ、SOC による検索、ユーザー招待、アクセストークンのローテーション、タグ管理、安全上の理由による拒否、サイト ID の検索、毎日のヘルスチェック、ESS 設定の変更、自動化された夜間ジョブをカバーします。

---

ロードマップ

リリース済み：

• 88件以上の VRM 操作に対応する53個のツール
• Streamable HTTP トランスポートと MCP Connector API のサポート
• セキュリティ強化（Origin／Accept／Content-Type／Protocol-Version、トークンの秘匿、確認ゲート、サイト許可リスト、ベース URL の固定）
• すべてのツールに outputSchema を設定
• 506件のテスト（オフライン415件＋ライブ91件）と Node 22／24 での CI
• 12件のシナリオ評価

予定：

• Cloudflare Workers アダプター（ステートレスに適したデプロイ）
• Docker イメージ
• VRM の 200-window／3 req/s に合わせたトークンバケット方式のレートリミッター
• 記録済みフィクスチャを使ったテスト（オフラインの VRM 応答スナップショット）
• VRM がカーソル方式のページネーションを追加した際に vrm_list_data_attributes をページネーション対応

---

参考資料

• VRM API ドキュメント
• VRM API ライブドキュメント（試用）
• Anthropic MCP Connector API
• Model Context Protocol 仕様
• Victron Energy 製品とのデータ通信（ホワイトペーパー）

ライセンス

MIT