aiseg2-mcp

aiseg2-mcp

日语版请参阅 README.ja.md。

一个非官方、只读的 Model Context Protocol 服务，用于连接 Panasonic AiSEG2 家庭能源管理（HEMS）控制器。它允许 MCP 客户端（例如 Claude）从 AiSEG2 的本地 Web 界面读取家庭的实时电力流、各电路用电量、电路名称和每日能源总量。

本项目与 Panasonic 无关，也未获得其认可。“AiSEG”是 Panasonic 的商标。

已验证环境

在以下环境中开发和测试：

• AiSEG2 型号 MKN713 系列
• 固件 Ver.2.97I-01

AiSEG2 Web 界面没有文档说明，且不同固件版本之间会有所变化。**在其他型号或固件版本上，本服务抓取的页面可能不同，部分工具可能无法使用。**如果遇到解析错误，请提交 issue，并注明型号和固件版本。

工具

所有工具均为只读（带有 readOnlyHint 注释、不会产生破坏性影响，并设有人类可读的 title）。服务只发送 GET 请求，以及 Web 界面自身使用的仅用于显示的刷新 POST 请求；绝不会修改设置或访问任何 /action/ 端点。

每个结果都包含 as_of（ISO 8601，UTC）：表示服务从 AiSEG2 读取数值的时间；对于两个历史工具，则表示其数据来源 SD 卡导出文件的下载时间。

工具	标题	返回内容
get_power_flow	当前电力流	即时发电量／用电量（kW）、购电／售电状态、电池状态、发电来源、用电量最高的电路
get_circuit_breakdown	当前各电路用电量	每个已测量电路的即时用电量（W），按从高到低排序，并附总量
list_circuits	已注册电路	已注册电路的 ID 和名称（权威命名来源）
get_daily_totals	今日能源总量	今日累计发电量／用电量／电网购电量／电网售电量（kWh）
get_history	能源历史记录	SD 卡导出文件中的长期能源历史记录（Wh），以长格式数据点返回。参数：granularity（30min／hour／day／month／year）、start／end（按粒度使用 YYYY-MM-DD、YYYY-MM 或 YYYY）、可选的 metrics／circuits 筛选条件、limit／offset 分页参数
get_cost_history	能源费用历史记录	SD 卡导出文件中的长期能源费用历史记录（JPY）。参数：granularity（day／month／year）、start／end、limit／offset

两个历史工具都要求在 AiSEG2 中插入 SD 卡——它们会读取设备导出的 SD 卡 CSV 文件。导出文件只会下载一次并缓存（参见 AISEG_CACHE_DIR／AISEG_CACHE_TTL），因此首次调用较慢，后续调用则会很快。

安装和运行

根据你的设置，有三种运行方式。

1. uvx（PyPI — 发布后）

对于本地（stdio）MCP 客户端，这是最简单的选项。需要安装 uv。

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

将其添加到 Claude Code：

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）

容器默认使用 streamable-http 传输方式（长期运行的网络服务）。请只在经过身份验证的代理后暴露它——参见安全。

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. 从源代码运行

需要 Python 3.12+ 和 uv。

uv sync
AISEG_URL=http://192.168.0.216 AISEG_PASSWORD=... uv run aiseg2-mcp

远程访问（经身份验证的 claude.ai 自定义连接器）

如果 AiSEG2 保持在你的局域网内，而你希望从 claude.ai 访问此服务，请参阅 examples/remote/——这是一个 Docker Compose 堆栈（MCP + GitHub-OAuth 代理 + Cloudflare Tunnel）。

运行镜像

本仓库的工作到将镜像推送到 GHCR 为止。镜像实际在哪里以及如何运行（Kubernetes 清单等）由其他地方定义——维护者自己的部署定义在 fumo-infra 中。下表列出了其他系统运行此镜像时所依据的约定。

镜像和标签	每次推送到 main 时使用 ghcr.io/chanyou0311/aiseg2-mcp:sha-<7hex>（创建时间戳 = 源提交的时间，而非构建时间）；vX.Y.Z 发布标签还会额外发布 X.Y.Z、X.Y 和 latest
监听端口	8000/tcp — 位于 /mcp 的 streamable-http MCP 端点
健康检查	存活检查：GET /health；就绪检查：通过 TCP 连接端口 8000
必需环境变量	AISEG_URL、AISEG_PASSWORD（密钥）
可选环境变量（默认值）	AISEG_USER（aiseg）、AISEG_TRANSPORT（streamable-http — 在镜像级别设置为 ENV；软件包本身的默认值（例如通过 uvx 运行时）为 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）——详情请参阅下文的配置（环境变量）

本仓库中没有部署定义（Kubernetes 清单）。

配置（环境变量）

变量	必需	默认值	描述
AISEG_URL	是	—	AiSEG2 基础 URL，例如 http://192.168.0.216（仅限 http）
AISEG_PASSWORD	是	—	AiSEG2 Web 界面的 HTTP Digest 密码
AISEG_USER	否	aiseg	HTTP Digest 用户名
AISEG_TRANSPORT	否	stdio	stdio 或 streamable-http
AISEG_HOST	否	0.0.0.0	绑定主机（仅限 streamable-http）
AISEG_PORT	否	8000	绑定端口（仅限 streamable-http）
AISEG_DISABLE_DNS_REBINDING_PROTECTION	否	false	禁用 Host 允许列表（默认仅接受 localhost / 127.0.0.1 / [::1] Host 标头）——仅在可信的身份验证代理后使用
AISEG_CACHE_DIR	否	<tempdir>/aiseg2-mcp-cache	SD 卡历史记录导出的缓存位置
AISEG_CACHE_TTL	否	3600	重新下载前复用缓存的历史记录导出的秒数
LOG_LEVEL	否	info	日志级别

安全

• 设计上仅限局域网使用。 AiSEG2 使用明文 HTTP 和 Digest 身份验证；请确保设备和此服务都位于可信的本地网络中。密码从环境变量读取，绝不会写入日志。
• 只读。 没有用于更改设备设置的工具。工具范围由测试强制执行（已注册工具允许列表、工具名称防护、对 /action/ 的源码扫描，以及只读注解检查）。
• 不要在未进行身份验证的情况下，将 streamable-http 传输暴露给不可信网络。 此服务本身不提供身份验证；如果将其作为网络服务运行，请在前面放置一个身份验证反向代理。AISEG_DISABLE_DNS_REBINDING_PROTECTION=true 仅适用于这种经过代理的配置。

致谢

AiSEG2 Web 界面没有文档说明；本项目基于先前工作分享的逆向工程知识构建：

• shimosyan/aiseg2-influxdb-forwarder — 电路分页中的“重复最后一页”终止机制及电流流量字段。
• hiroaki0923/aiseg2-bridge — 端点和页面结构。
• Bugfire/aiseg_download — Digest 身份验证和数据端点约定。

许可证

MIT