el-mcp-server

ECHONET Lite の情報を AI から利用可能にする MCP (Model Context Protocol) サーバーです。Go で実装しています。

提供する MCP ツール

4 系統のツール群があります。set_property を除くすべてのツールは読み取り専用（ReadOnlyHint: true）です:

• 仕様検索 — 埋め込み (//go:embed) MRA JSON をプロセス内で検索 (外部通信なし)
• 機器通信 — LAN 上の ECHONET Lite 機器へ UDP で問い合わせ
• 製品検索 — echonet.jp へ HTTP でリクエスト
• UI 表示 — 機器通信結果を MCP Apps 対応クライアントでダッシュボード表示

仕様検索（静的データ）

ECHONET Lite Appendix の公式機械可読版 MRA (Machine Readable Appendix) の JSON データを埋め込んで検索します。

ツール	概要
search_device_class	名前・キーワード・EOJ コードで機器クラスを検索
list_epc	機器クラスの EPC（プロパティコード）一覧を取得
get_epc_detail	特定 EPC の詳細（データ型・単位・アクセス規則）を取得

収録機器クラス（全 16 クラス）:

• ノードプロファイル (0EF0XX)
• 温度センサ (0011XX)
• 湿度センサ (0012XX)
• CO2 センサ (001BXX)
• 家庭用エアコン (0130XX)
• 電気温水器 (026BXX)
• 瞬間式給湯器 (0272XX)
• 住宅用太陽光発電 (0279XX)
• 床暖房 (027BXX)
• 燃料電池 (027CXX)
• 蓄電池 (027DXX)
• 電気自動車充放電器 (027EXX)
• 分電盤メータリング (0287XX)
• 低圧スマート電力量メータ (0288XX)
• 一般照明 (0290XX)
• 電気自動車充電器 (02A1XX)

ECHONET Lite 機器通信（UDP / LAN）

同一 LAN 上の ECHONET Lite 機器と UDP（ポート 3610）で通信します。

ツール	概要
discover_devices	マルチキャスト（224.0.23.0）で LAN 内の機器を探索
get_property	指定機器の EPC プロパティ値を Get で取得。EPC 8A（メーカーコード）は manufacturer_name フィールドも自動付与
set_property	指定機器の EPC プロパティ値を SetC（応答あり）で書き込み。機器の実際の状態を変更します（ReadOnlyHint: false / DestructiveHint: true）。書き込み可否・EDT の形式は事前に get_epc_detail で確認してください

製品検索（HTTP）

ツール	概要
search_certified_products	echonet.jp の認証登録製品を検索

UI 表示（MCP Apps）

機器の状態を取得し、MCP Apps（SEP-1865）対応クライアントでは ui://el-mcp-server/<機器> のダッシュボードとして表示します。

ツール	概要
render_battery_ui	蓄電池(EOJ 027Dxx)の稼働状態・運転モード・蓄電残量・充放電電力を表示。稼働状態と運転モードを操作可能
render_solar_ui	住宅用太陽光発電(EOJ 0279xx)の稼働状態・瞬時発電電力・積算発電/売電電力量・系統連系状態・出力抑制状態を表示。読み取り専用
render_v2h_ui	V2H(EOJ 027Exx)の稼働状態・運転モード・車載電池残容量・充放電電力・積算充放電電力量・車両接続状態を表示。稼働状態と運転モードを操作可能
render_aircon_ui	家庭用エアコン(EOJ 0130xx)の稼働状態・運転モード・設定温度・室内温度・風量を表示。稼働状態・運転モード・設定温度・風量を操作可能
render_smartmeter_ui	低圧スマート電力量メータ(EOJ 0288xx)の稼働状態・瞬時電力・瞬時電流・積算電力量と、date(省略時は今日)で指定した日の 30 分毎の買電/売電電力量をグラフ/表で表示。前日/翌日へ移動可能。履歴の取得時に積算履歴収集日(EPC E5)を書き換え、取得後に元の値へ戻す

MCP Apps 未対応のクライアント（Claude Code CLI など）では、通常のツール同様に JSON がそのまま返ります。

アーキテクチャ

4 種のツール群はデータの取得方法が異なります。

仕様検索（静的データ）

MRA JSON はビルド時にバイナリへ埋め込まれます。ツール呼び出し時の外部通信はなく、プロセス内で完結します。

sequenceDiagram
    participant AI as AI (MCP クライアント)
    participant S as el-mcp-server

    Note over AI,S: MCP プロトコル (stdio / HTTP)

    AI->>+S: tools/call search_device_class / list_epc / get_epc_detail
    Note over S: 埋め込み MRA JSON を検索<br/>（外部通信なし）
    S-->>-AI: 機器クラス / EPC 定義

ECHONET Lite 機器通信（UDP / LAN）

ツール呼び出しのたびに同一 LAN 上の機器へ UDP でリアルタイムに問い合わせます（オンデマンド型。事前のデータ蓄積はしません）。

sequenceDiagram
    participant AI as AI (MCP クライアント)
    participant S as el-mcp-server
    participant D as ECHONET Lite 機器<br/>(同一 LAN)

    Note over AI,S: MCP プロトコル (stdio / HTTP)

    AI->>+S: tools/call discover_devices
    S->>+D: UDP マルチキャスト 224.0.23.0:3610<br/>Get インスタンスリスト (EPC D6)
    D-->>-S: Get_Res (保有オブジェクトの EOJ 一覧)
    S-->>-AI: 機器の IP / EOJ 一覧

    AI->>+S: tools/call get_property (ip, eoj, epc)
    S->>+D: UDP ユニキャスト <ip>:3610<br/>Get (指定 EPC)
    D-->>-S: Get_Res (プロパティ値 EDT)
    S-->>-AI: プロパティ値 (hex)

    AI->>+S: tools/call set_property (ip, eoj, epc, edt)
    S->>+D: UDP ユニキャスト <ip>:3610<br/>SetC (指定 EPC, 書き込み値 EDT)
    D-->>-S: Set_Res (成功) または SetC_SNA (失敗)
    S-->>-AI: 書き込み結果

discover_devices / get_property / set_property が通信できるのは、el-mcp-server を起動したマシンが属する LAN 上の機器のみです。

同一ホスト上で ECHONET Lite エミュレータと el-mcp-server を併用する場合、両者が UDP ポート 3610 を同時に占有できないため discover_devices は使用できません。エミュレータの IP（127.0.0.1）と EOJ があらかじめわかっている場合は、discover_devices を経由せず直接 get_property / set_property を呼び出してください。

set_property は SetC のみに対応しています（応答を待たずに成否が確認できない SetI は未対応）。EPC が書き込み不可、または EDT の形式が不正な場合、機器は SetC_SNA を返し、ツールはエラーとして報告します。

製品検索（HTTP）

ツール呼び出し時に echonet.jp へ HTTP リクエストを送り、レスポンスの HTML をパースして返します。

sequenceDiagram
    participant AI as AI (MCP クライアント)
    participant S as el-mcp-server
    participant W as echonet.jp

    Note over AI,S: MCP プロトコル (stdio / HTTP)

    AI->>+S: tools/call search_certified_products
    S->>+W: HTTP GET /product/echonet-lite/<br/>（con_manufacturer / con_product_type / pro_num）
    W-->>-S: HTML レスポンス
    Note over S: HTML をパースして製品一覧を抽出
    S-->>-AI: 製品名・メーカー・認証番号 等

UI 表示（MCP Apps）

render_*_ui は内部で ECHONET Lite 機器通信（UDP）を行い、取得結果を通常の CallToolResult として返します。MCP Apps 対応クライアントはツール定義の _meta.ui.resourceUri を見て、埋め込み (//go:embed) 済みの HTML（tools/ui/templates/*.html）をダッシュボードとして描画します。返す JSON（structuredContent）の命名規則は各ツールで揃えています（snake_case、単位サフィックス _w / _percent / _kwh）。

sequenceDiagram
    participant AI as AI (MCP Apps クライアント)
    participant S as el-mcp-server
    participant D as 蓄電池<br/>(同一 LAN, EOJ 027Dxx)

    Note over AI,S: MCP プロトコル (stdio / HTTP)

    AI->>+S: tools/call render_battery_ui (ip, eoj)
    S->>+D: UDP ユニキャスト <ip>:3610<br/>Get (稼働状態・運転モード・蓄電残量・充放電電力)
    D-->>-S: Get_Res (プロパティ値 EDT)
    S-->>-AI: CallToolResult (JSON) + _meta.ui.resourceUri
    Note over AI: resources/read ui://el-mcp-server/battery<br/>で HTML を取得しダッシュボード描画

    Note over AI: ユーザーがダッシュボード上で<br/>稼働状態トグル / 運転モードを操作
    AI->>+S: tools/call set_property (ip, eoj, epc, edt)
    S->>+D: UDP ユニキャスト <ip>:3610<br/>SetC (EPC 80: 稼働状態 または EPC DA: 運転モード)
    D-->>-S: Set_Res (成功) または SetC_SNA (失敗)
    S-->>-AI: 書き込み結果
    AI->>+S: tools/call render_battery_ui (ip, eoj)
    Note over S,D: 最新状態を再取得
    S-->>-AI: CallToolResult (JSON)<br/>ダッシュボードを最新状態で再描画

ダッシュボードは MCP Apps の postMessage ブリッジ経由でホストに tools/call を直接送信できるため、操作系のコントロールは AI を介さず set_property → render_*_ui(再取得)を呼び出して画面を更新します。スマートメーターの前日/翌日ボタンも同じ仕組みで render_smartmeter_ui を呼び出します。

インストール

Go 1.26 以上が必要です。

go install github.com/thekuwayama/el-mcp-server@latest

バイナリは $(go env GOPATH)/bin/el-mcp-server に配置されます。更新するときは同じコマンドを再実行してください。

Claude Code

claude mcp add -s user el-mcp-server -- "$(go env GOPATH)/bin/el-mcp-server"

• -s user は、どのディレクトリで Claude Code を起動しても使えるユーザースコープです。省略すると、コマンドを実行したディレクトリ専用の Local スコープになります
• 登録内容と接続状態は claude mcp get el-mcp-server で確認できます

Claude Desktop

Releases から、お使いの環境に合った .mcpb をダウンロードし、Claude Desktop にドラッグ & ドロップ、または「拡張機能を追加」から選択してください。

環境	ファイル
macOS（Apple Silicon）	el-mcp-server_<version>_darwin_arm64.mcpb
Windows（x64）	el-mcp-server_<version>_windows_amd64.mcpb

• Windows では、機器の探索・通信に UDP 3610 番ポートを使用するため、初回起動時に Windows Defender ファイアウォールで通信を許可する必要があります。なお、Windows での動作確認は限定的です
• .mcpb は MCP Bundle 形式のため、Claude Desktop 以外の .mcpb 対応クライアントでも同じ手順で導入できます

登録後、Claude に「LAN 内の ECHONET Lite 機器を探して」「スマートメーターの EPC 一覧を教えて」「192.168.1.50 の蓄電池を UI 表示して」「192.168.1.60 の太陽光発電を UI 表示して」「192.168.1.70 の V2H を UI 表示して」「192.168.1.100 のエアコンの運転モードを冷房にして」のように話しかけると各ツールが呼び出されます。

開発者向け（ソースからビルド）

git clone git@github.com:thekuwayama/el-mcp-server.git

cd el-mcp-server

make build

go install .

起動

stdio モード（デフォルト）

el-mcp-server

HTTP モード（Streamable HTTP）

el-mcp-server -transport http -addr :8080

データソース

• ECHONET Lite 規格書 Ver.1.14 — フレーム構造・UDP 通信仕様
• MRA (Machine Readable Appendix) v1.4.0 — 機器クラス・EPC 定義。Appendix Release R の公式 JSON 版を echonet/spec/mra/ に収録し、ビルド時に埋め込み
• ECHONET Lite 認証製品検索 — search_certified_products が実行時に取得
• メーカーコード一覧 — EPC 8A の解決用。echonet/spec/manufacturers/codes.json に収録し、ビルド時に埋め込み。/update-manufacturer-codes スキルで更新可能

仕様は echonet.jp の仕様総合ページ から辿れます。

MRA データ更新手順

echonet/spec/mra/ の JSON を最新の MRA (Machine Readable Appendix) に差し替える手順は Claude Code スキル /update-mra（.claude/skills/update-mra/SKILL.md）を参照してください。cmd/update-mra が VERSION 比較・ダウンロード・展開・コピーをまとめて行います。

制限事項

• 認証機構を実装していません。MCP の Authorization 仕様では、認証をサポートする場合、HTTP ベーストランスポートの実装は OAuth 2.1 ベースの同仕様に準拠すべき（SHOULD）とされていますが、本サーバーは未対応です。HTTP モードは信頼できるネットワーク内でのみ使用してください
• 機器への書き込みは set_property（SetC）のみ対応しています。SetI（応答なしの書き込み）は未実装です
• set_property は機器の実際の状態（運転モード・温度設定など）を変更します。呼び出し前に対象 EPC が書き込み可能か、EDT が正しい形式かを get_epc_detail で確認してください
• search_certified_products の keyword は echonet.jp に server 側でクエリを渡して絞り込みますが、maker / category は echonet.jp 側が確実に絞り込まないため、取得した結果をクライアント側で再フィルタしています。最大 5 ページ（60 件）分しか走査しないため、該当件数が多いカテゴリでは一致する製品でも取得できない場合があります
• discover_devices / get_property / set_property は IPv4（UDP4ソケット）のみに対応しています。IPv6 の ECHONET Lite 機器（マルチキャストアドレス FF02::1）は探索・操作できません