Aiseg2 Mcp

io.github.chanyou0311由 GitHub 帳號 chanyou0311 發布v0.1.0更新於 Oct 24, 2026

Unofficial read-only MCP server for the Panasonic AiSEG2 HEMS controller.

已驗證STDIO僅桌面位置與生活資料與分析

概覽

AI 產生的概覽

非官方唯讀 MCP 伺服器,讓助理讀取 Panasonic AiSEG2 家庭能源管理控制器的即時電力流向、分回路用電與能源歷史。

可以做什麼
  • 讀取即時電力流向:瞬時發電與用電、買電/賣電狀態、電池狀態及耗電最高的回路
  • 檢視回路:依用電量由高到低排列的各回路瞬時功率,以及已登記回路的編號與名稱
  • 讀取當日能源彙總:累計發電、用電、購電與售電
  • 查詢長期能源歷史:支援 30 分鐘至年度的粒度,可依指標與回路篩選並分頁
  • 查詢費用歷史:依日、月或年檢視以日圓計的長期能源費用歷史
適用情境
適合讓助理回答家中太陽能、電池及各回路用電情況的問題,或回顧區域網路內 AiSEG2 的歷史用電與費用趨勢。
執行需求
以 stdio 方式在本機執行,通常透過 PyPI 的 uvx(需安裝 uv)或從原始碼執行(需 Python 3.12 以上),另提供容器映像。需要 AISEG_URL(AiSEG2 基礎位址,僅支援 http)與 AISEG_PASSWORD(HTTP Digest 密碼),AISEG_USER 預設為 aiseg。兩個歷史工具需要 AiSEG2 中插入 SD 卡,並會在本機快取匯出檔。
安裝前請注意
AISEG_PASSWORD 屬機密,且會以明文 HTTP 傳送給裝置,請將兩者都限制在可信任的區域網路內。伺服器本身不具認證;若以 streamable-http 網路服務方式執行,應在前方加上具認證的反向代理,並避免關閉 DNS 重綁定保護。本專案為非官方,未在其他型號或韌體上驗證,可能出現解析失敗。工具為唯讀,不會變更裝置設定。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Aiseg2 Mcp,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

aiseg2-mcp

日本語版は README.ja.md をご覧ください。

An unofficial, read-only Model Context Protocol server for the Panasonic AiSEG2 home energy management (HEMS) controller. It lets an MCP client (e.g. Claude) read your home's live power flow, per-circuit consumption, circuit names, and daily energy totals from the AiSEG2's local web interface.

This project is not affiliated with or endorsed by Panasonic. "AiSEG" is a Panasonic trademark.

Verified environment

Developed and tested against:

  • AiSEG2 model MKN713 series
  • Firmware Ver.2.97I-01

The AiSEG2 web interface is undocumented and changes between firmware revisions. On a different model or firmware the pages this server scrapes may differ and some tools may not work. If you hit a parse error, please open an issue with your model / firmware version.

Tools

All tools are read-only (annotated readOnlyHint, non-destructive, with a human-readable title). The server only issues GETs and the display-only refresh POSTs the web UI itself uses; it never touches settings or any /action/ endpoint.

Every result carries as_of (ISO 8601, UTC): when the server read the values from the AiSEG2, or for the two history tools, when the SD-card export behind them was downloaded.

ToolTitleReturns
get_power_flowCurrent power flowInstantaneous generation/consumption (kW), buy/sell state, battery status, generation sources, top consuming circuits
get_circuit_breakdownCurrent power by circuitEvery measured circuit's instantaneous draw (W), ranked highest first, with the total
list_circuitsRegistered circuitsRegistered circuit ids and names (the authoritative naming source)
get_daily_totalsToday's energy totalsToday's cumulative generation / consumption / grid-buy / grid-sell (kWh)
get_historyEnergy historyLong-term energy history from the SD-card export (Wh), long-form points. Args: granularity (30min/hour/day/month/year), start/end (per granularity: YYYY-MM-DD, YYYY-MM, or YYYY), optional metrics/circuits filters, limit/offset paging
get_cost_historyEnergy cost historyLong-term energy-cost history from the SD-card export (JPY). Args: granularity (day/month/year), start/end, limit/offset

The two history tools require an SD card inserted in the AiSEG2 — they read the device's SD-card CSV export. The export is downloaded once and cached (see AISEG_CACHE_DIR / AISEG_CACHE_TTL), so the first call is slow and later calls are fast.

Install & run

Three ways to run it, depending on your setup.

1. uvx (PyPI — once published)

The simplest option for a local (stdio) MCP client. Requires uv.

bash
AISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uvx aiseg2-mcp

Add it to Claude Code:

bash
claude mcp add aiseg2 \  --env AISEG_URL=http://192.168.0.216 \  --env AISEG_PASSWORD=your-digest-password \  -- uvx aiseg2-mcp

2. docker run (GHCR)

The container defaults to the streamable-http transport (long-lived network service). Only expose it behind an authenticating proxy — see Security.

bash
docker run --rm -p 8000:8000 \  -e AISEG_URL=http://192.168.0.216 \  -e AISEG_PASSWORD=your-digest-password \  ghcr.io/chanyou0311/aiseg2-mcp:latest

3. From source

Requires Python 3.12+ and uv.

bash
uv syncAISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uv run aiseg2-mcp

Remote (authenticated claude.ai Custom Connector)

To reach the server from claude.ai while your AiSEG2 stays on your LAN, see examples/remote/ — a Docker Compose stack (MCP + GitHub-OAuth proxy + Cloudflare Tunnel).

Running the image

This repo's job ends at pushing the image to GHCR. Where and how it actually runs (Kubernetes manifests, etc.) is defined elsewhere — for the maintainer's own deployment, in fumo-infra. The table below is the contract another system builds against to run this image.

Image & tagsghcr.io/chanyou0311/aiseg2-mcp:sha-<7hex> on every push to main (created timestamp = the source commit's time, not the build time); a vX.Y.Z release tag additionally publishes X.Y.Z, X.Y, and latest
Listens on8000/tcp — streamable-http MCP endpoint at /mcp
Health checksliveness: GET /health; readiness: TCP connect on port 8000
Required envAISEG_URL, AISEG_PASSWORD (secret)
Optional env (default)AISEG_USER (aiseg), AISEG_TRANSPORT (streamable-http — set as an image-level ENV; the package's own default, e.g. when run via uvx, is stdio), AISEG_HOST (0.0.0.0), AISEG_PORT (8000), AISEG_DISABLE_DNS_REBINDING_PROTECTION (false), AISEG_CACHE_DIR (<tempdir>/aiseg2-mcp-cache), AISEG_CACHE_TTL (3600), LOG_LEVEL (info) — see Configuration below for details

There is no deployment definition (Kubernetes manifests) in this repo.

Configuration (environment variables)

VariableRequiredDefaultDescription
AISEG_URLyes—AiSEG2 base URL, e.g. http://192.168.0.216 (http only)
AISEG_PASSWORDyes—HTTP Digest password for the AiSEG2 web UI
AISEG_USERnoaisegHTTP Digest user
AISEG_TRANSPORTnostdiostdio or streamable-http
AISEG_HOSTno0.0.0.0Bind host (streamable-http only)
AISEG_PORTno8000Bind port (streamable-http only)
AISEG_DISABLE_DNS_REBINDING_PROTECTIONnofalseDisable the Host allowlist (by default only localhost / 127.0.0.1 / [::1] Host headers are accepted) — only behind a trusted auth proxy
AISEG_CACHE_DIRno<tempdir>/aiseg2-mcp-cacheWhere the SD-card history export is cached
AISEG_CACHE_TTLno3600Seconds to reuse a cached history export before re-downloading
LOG_LEVELnoinfoLog level

Security

  • LAN-only by design. The AiSEG2 speaks plain HTTP with Digest auth; keep it and this server on a trusted local network. The password is read from the environment and is never logged.
  • Read-only. There is no tool that changes a device setting. The tool surface is enforced by tests (registered-tool allowlist, tool-name guard, a source scan for /action/, and read-only annotation checks).
  • Do not expose the streamable-http transport to untrusted networks without authentication. This server carries no auth of its own; if you run it as a network service, put an authenticating reverse proxy in front of it. AISEG_DISABLE_DNS_REBINDING_PROTECTION=true is only appropriate in that proxied setup.

Acknowledgements

The AiSEG2 web interface is undocumented; this project builds on the reverse-engineering knowledge shared by prior work:

License

MIT

來源:README.md,提交 9b34317

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

1
  1. v0.1.0最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分