{
  "markdown": "<!-- mcp-name: io.github.chanyou0311/aiseg2-mcp -->\n\n# aiseg2-mcp\n\n日本語版は [README.ja.md](./README.ja.md) をご覧ください。\n\nAn **unofficial, read-only** [Model Context Protocol](https://modelcontextprotocol.io) server for\nthe **Panasonic AiSEG2** home energy management (HEMS) controller. It lets an MCP client (e.g.\nClaude) read your home's live power flow, per-circuit consumption, circuit names, and daily energy\ntotals from the AiSEG2's local web interface.\n\nThis project is not affiliated with or endorsed by Panasonic. \"AiSEG\" is a Panasonic trademark.\n\n## Verified environment\n\nDeveloped and tested against:\n\n- AiSEG2 model **MKN713** series\n- Firmware **Ver.2.97I-01**\n\nThe AiSEG2 web interface is undocumented and changes between firmware revisions. **On a different\nmodel or firmware the pages this server scrapes may differ and some tools may not work.** If you hit\na parse error, please open an issue with your model / firmware version.\n\n## Tools\n\nAll tools are **read-only** (annotated `readOnlyHint`, non-destructive). The server only issues\nGETs and the display-only refresh POSTs the web UI itself uses; it never touches settings or any\n`/action/` endpoint.\n\n| Tool | Returns |\n|---|---|\n| `get_power_flow` | Instantaneous generation/consumption (kW), buy/sell state, battery status, generation sources, top consuming circuits |\n| `get_circuit_breakdown` | Every measured circuit's instantaneous draw (W), ranked highest first, with the total |\n| `list_circuits` | Registered circuit ids and names (the authoritative naming source) |\n| `get_daily_totals` | Today's cumulative generation / consumption / grid-buy / grid-sell (kWh) |\n| `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 |\n| `get_cost_history` | Long-term energy-cost history from the SD-card export (JPY). Args: `granularity` (`day`/`month`/`year`), `start`/`end`, `limit`/`offset` |\n\n> **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.\n\n## Install & run\n\nThree ways to run it, depending on your setup.\n\n### 1. uvx (PyPI — once published)\n\nThe simplest option for a local (stdio) MCP client. Requires [uv](https://docs.astral.sh/uv/).\n\n```bash\nAISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uvx aiseg2-mcp\n```\n\nAdd it to Claude Code:\n\n```bash\nclaude mcp add aiseg2 \\\n  --env AISEG_URL=http://192.168.0.216 \\\n  --env AISEG_PASSWORD=your-digest-password \\\n  -- uvx aiseg2-mcp\n```\n\n### 2. docker run (GHCR)\n\nThe container defaults to the `streamable-http` transport (long-lived network service). Only expose\nit behind an authenticating proxy — see [Security](#security).\n\n```bash\ndocker run --rm -p 8000:8000 \\\n  -e AISEG_URL=http://192.168.0.216 \\\n  -e AISEG_PASSWORD=your-digest-password \\\n  ghcr.io/chanyou0311/aiseg2-mcp:latest\n```\n\n### 3. From source\n\nRequires Python 3.12+ and uv.\n\n```bash\nuv sync\nAISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uv run aiseg2-mcp\n```\n\n### Remote (authenticated claude.ai Custom Connector)\n\nTo reach the server from claude.ai while your AiSEG2 stays on your LAN, see\n[`examples/remote/`](./examples/remote/) — a Docker Compose stack (MCP + GitHub-OAuth proxy +\nCloudflare Tunnel).\n\n## Configuration (environment variables)\n\n| Variable | Required | Default | Description |\n|---|---|---|---|\n| `AISEG_URL` | yes | — | AiSEG2 base URL, e.g. `http://192.168.0.216` (http only) |\n| `AISEG_PASSWORD` | yes | — | HTTP Digest password for the AiSEG2 web UI |\n| `AISEG_USER` | no | `aiseg` | HTTP Digest user |\n| `AISEG_TRANSPORT` | no | `stdio` | `stdio` or `streamable-http` |\n| `AISEG_HOST` | no | `0.0.0.0` | Bind host (streamable-http only) |\n| `AISEG_PORT` | no | `8000` | Bind port (streamable-http only) |\n| `AISEG_DISABLE_DNS_REBINDING_PROTECTION` | no | `false` | Disable the SDK Host allowlist — **only** behind a trusted auth proxy |\n| `AISEG_CACHE_DIR` | no | `<tempdir>/aiseg2-mcp-cache` | Where the SD-card history export is cached |\n| `AISEG_CACHE_TTL` | no | `3600` | Seconds to reuse a cached history export before re-downloading |\n| `LOG_LEVEL` | no | `info` | Log level |\n\n## Security\n\n- **LAN-only by design.** The AiSEG2 speaks plain HTTP with Digest auth; keep it and this server on\n  a trusted local network. The password is read from the environment and is never logged.\n- **Read-only.** There is no tool that changes a device setting. The tool surface is enforced by\n  tests (registered-tool allowlist, tool-name guard, a source scan for `/action/`, and read-only\n  annotation checks).\n- **Do not expose the `streamable-http` transport to untrusted networks without authentication.**\n  This server carries no auth of its own; if you run it as a network service, put an authenticating\n  reverse proxy in front of it. `AISEG_DISABLE_DNS_REBINDING_PROTECTION=true` is only appropriate in\n  that proxied setup.\n\n## Acknowledgements\n\nThe AiSEG2 web interface is undocumented; this project builds on the reverse-engineering knowledge\nshared by prior work:\n\n- [shimosyan/aiseg2-influxdb-forwarder](https://github.com/shimosyan/aiseg2-influxdb-forwarder) — the circuit-paging \"repeat the last page\" terminator and the electric-flow fields.\n- [hiroaki0923/aiseg2-bridge](https://github.com/hiroaki0923/aiseg2-bridge) — endpoint and page structure.\n- [Bugfire/aiseg_download](https://github.com/Bugfire/aiseg_download) — Digest auth and data-endpoint conventions.\n\n## License\n\n[MIT](./LICENSE)\n",
  "bytes": 5743,
  "sha": "0c59484a41ba242549e932dcffa0b488a23c35a1785d51450a5bde4e6320635b",
  "repo_slug": "chanyou0311/aiseg2-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_chanyou0311_aiseg2_mcp_f42ca209/readme"
}