el-mcp-server
by thekuwayama
README.md
# el-mcp-server
[](https://github.com/thekuwayama/el-mcp-server/actions/workflows/ci.yaml)
[](https://echonet.jp/spec_mra_rr3/)
[](LICENSE.txt)
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)](https://echonet.jp/spec_mra_rr3/) の 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](https://echonet.jp/product/echonet-lite/) の認証登録製品を検索 |
### UI 表示(MCP Apps)
機器の状態を取得し、[MCP Apps](https://modelcontextprotocol.io/community/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp)(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 はビルド時にバイナリへ埋め込まれます。ツール呼び出し時の外部通信はなく、プロセス内で完結します。
```mermaid
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 でリアルタイムに問い合わせます(オンデマンド型。事前のデータ蓄積はしません)。
```mermaid
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 をパースして返します。
```mermaid
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`)。
```mermaid
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 以上が必要です。
```bash
go install github.com/thekuwayama/el-mcp-server@latest
```
バイナリは `$(go env GOPATH)/bin/el-mcp-server` に配置されます。更新するときは同じコマンドを再実行してください。
### Claude Code
```bash
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](https://github.com/thekuwayama/el-mcp-server/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](https://github.com/anthropics/mcpb) 形式のため、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 のエアコンの運転モードを冷房にして」のように話しかけると各ツールが呼び出されます。
### 開発者向け(ソースからビルド)
```bash
git clone git@github.com:thekuwayama/el-mcp-server.git
cd el-mcp-server
make build
go install .
```
#### 起動
stdio モード(デフォルト)
```bash
el-mcp-server
```
HTTP モード(Streamable HTTP)
```bash
el-mcp-server -transport http -addr :8080
```
## データソース
- [ECHONET Lite 規格書 Ver.1.14](https://echonet.jp/spec_v114_lite/) — フレーム構造・UDP 通信仕様
- [MRA (Machine Readable Appendix) v1.4.0](https://echonet.jp/spec_mra_rr3/) — 機器クラス・EPC 定義。Appendix Release R の公式 JSON 版を `echonet/spec/mra/` に収録し、ビルド時に埋め込み
- [ECHONET Lite 認証製品検索](https://echonet.jp/product/echonet-lite/) — `search_certified_products` が実行時に取得
- [メーカーコード一覧](https://echonet.jp/wp/wp-content/uploads/pdf/General/Echonet/ManufacturerCode/list_code.xlsx) — EPC `8A` の解決用。`echonet/spec/manufacturers/codes.json` に収録し、ビルド時に埋め込み。`/update-manufacturer-codes` スキルで更新可能
仕様は [echonet.jp の仕様総合ページ](https://echonet.jp/spec_g/) から辿れます。
## MRA データ更新手順
`echonet/spec/mra/` の JSON を最新の MRA (Machine Readable Appendix) に差し替える手順は Claude Code スキル `/update-mra`([`.claude/skills/update-mra/SKILL.md`](.claude/skills/update-mra/SKILL.md))を参照してください。`cmd/update-mra` が VERSION 比較・ダウンロード・展開・コピーをまとめて行います。
## 制限事項
- 認証機構を実装していません。[MCP の Authorization 仕様](https://modelcontextprotocol.io/specification/2025-06-18/basic/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`)は探索・操作できません
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues