# aiseg2-mcp [Health: Active]

**Category:** 🏠 Home Automation  
**Repository:** https://github.com/chanyou0311/aiseg2-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/aiseg2-mcp

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

## Tools
Capabilities this server exposes over MCP:

- **get_power_flow** — Instantaneous generation/consumption (kW), buy/sell state, battery status, generation sources, top consuming circuits
- **get_circuit_breakdown** — Every measured circuit's instantaneous draw (W), ranked highest first, with the total
- **list_circuits** — Registered circuit ids and names (the authoritative naming source)
- **get_daily_totals** — Today's cumulative generation / consumption / grid-buy / grid-sell (kWh)
- **get_history** — Long-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_history** — Long-term energy-cost history from the SD-card export (JPY). Args: `granularity` (`day`/`month`/`year`), `start`/`end`, `limit`/`offset

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "aiseg2-mcp": {
    "command": "uvx",
    "args": ["aiseg2-mcp"],
    "env": {
      "AISEG_URL": "",
      "AISEG_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `AISEG_URL`, `AISEG_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What aiseg2-mcp MCP server does

The aiseg2-mcp MCP server exposes read-only energy data from a Panasonic AiSEG2 home energy management controller. It is intended for MCP clients that need to inspect household electricity information through the controller's local web interface, rather than operate or configure the device.

Live tools report current generation and consumption in kW, whether electricity is being bought or sold, battery state, generation sources, and the circuits using the most power. Circuit data can also be returned for every measured circuit in watts, ordered from highest consumption to lowest. A separate listing provides the registered circuit IDs and names used by the controller.

Daily totals cover cumulative generation, consumption, grid purchases, and grid sales for the current day. Historical tools read the AiSEG2's SD-card export and return energy measurements in Wh or energy costs in JPY.

## How it works

The server authenticates to the AiSEG2 web interface with HTTP Digest authentication and reads the pages and export data needed by its tools. It does not expose device-control operations: the tools are marked read-only, and the implementation does not use the controller's action endpoints. Each result includes an `as_of` timestamp in UTC showing when the live value was read or when the history export was downloaded.

`get_history` supports 30-minute, hourly, daily, monthly, and yearly data. It accepts date ranges appropriate to the selected granularity, optional metric and circuit filters, and limit/offset pagination. `get_cost_history` supports daily, monthly, and yearly cost data with date ranges and pagination.

The history export is cached after download. The first history request may therefore be slower, while later requests can reuse the cached file until its configured time-to-live expires. An SD card must be inserted in the AiSEG2 for either history tool to work.

## Setup and configuration

Run the package with `uvx`, from source with Python 3.12+ and `uv`, or as the published GHCR container. Set `AISEG_URL` to the controller's HTTP base URL and `AISEG_PASSWORD` to its Digest-auth password. `AISEG_USER` defaults to `aiseg`.

The package defaults to stdio transport. The container defaults to streamable HTTP on port 8000, with the MCP endpoint at `/mcp` and a health endpoint at `/health`. Transport, bind host, port, cache directory, cache lifetime, and log level can be changed with the documented environment variables.

## Tools and capabilities

- `get_power_flow`: reads instantaneous flow, battery state, buying or selling state, sources, and top-consuming circuits.
- `get_circuit_breakdown`: returns measured circuit loads and their total, ranked by watts.
- `list_circuits`: returns the controller's registered circuit IDs and names.
- `get_daily_totals`: returns today's cumulative energy figures.
- `get_history`: queries long-term energy export data with granularity, filters, and pagination.
- `get_cost_history`: queries long-term cost export data in JPY.

## Limitations and notes

The aiseg2-mcp MCP server is unofficial and is not affiliated with Panasonic. Its web-interface parsing was verified against MKN713-series AiSEG2 devices running firmware Ver.2.97I-01; undocumented page changes on other versions may cause tools to fail.

The AiSEG2 and server are designed for a trusted LAN because the controller uses plain HTTP. A streamable-HTTP deployment has no built-in authentication and should be placed behind an authenticating reverse proxy before being exposed beyond a trusted network. Keep `AISEG_DISABLE_DNS_REBINDING_PROTECTION` disabled unless that proxied arrangement is in use.

_Full upstream README: https://allmcps.com/mcp/aiseg2-mcp/readme_