Aiseg2 Mcp

io.github.chanyou0311Published by GitHub account chanyou0311v0.1.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

Unofficial read-only MCP server that lets an assistant read live power flow, per-circuit usage and energy history from a Panasonic AiSEG2 HEMS controller.

What you can do
  • Read live power flow: instantaneous generation and consumption, buy/sell state, battery status and top consuming circuits
  • Inspect circuits: current draw per measured circuit ranked highest first, plus registered circuit ids and names
  • Read today's energy totals: cumulative generation, consumption, grid buy and grid sell
  • Query long-term history: energy history in 30-minute to yearly granularity with metric and circuit filters and paging
  • Query cost history: long-term energy cost history in JPY by day, month or year
When to use it
Useful when you want an assistant to answer questions about your home's solar, battery and circuit-level electricity use, or to review past energy and cost trends from an AiSEG2 on your local network.
Requirements
Runs locally over stdio, typically via uvx from PyPI (requires uv) or from source with Python 3.12+; a container image is also published. Needs AISEG_URL (the AiSEG2 base URL, http only) and AISEG_PASSWORD (HTTP Digest password); AISEG_USER defaults to aiseg. The two history tools require an SD card in the AiSEG2 and cache the export locally.
Before you install
AISEG_PASSWORD is a secret sent to the device over plain HTTP, so keep both on a trusted LAN. The server has no authentication of its own; if run as a streamable-http network service, put an authenticating proxy in front and avoid disabling DNS rebinding protection. It is unofficial and untested on other models or firmware, so parsing may fail. Read-only: no tool changes device settings.

Installation

In SourceWeft

  1. Open Aiseg2 Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit 9b34317

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts