Goodwe Inverter Mcp Server

GoodWe 逆变器 MCP 服务

用于通过本地网络监控和控制 GoodWe 太阳能逆变器 的 MCP 服务。

基于 goodwe 库和 Model Context Protocol Python SDK 构建。

基于 Home Assistant GoodWe 集成 构建——传感器定义、运行模式、设置和逆变器系列支持均直接参考该实现。

功能

• 读取实时运行数据：光伏发电量、电池状态、电网输入/输出功率、负载功耗
• 读取和写入所有可配置的逆变器设置
• 切换运行模式（通用、节能、备用、削峰、离网等）
• 控制电网馈电限制和电池放电深度
• 7 个 MCP 资源：状态、运行数据、设置、功率流、每日能量、电池、传感器目录
• 6 个内置提示词模板，适用于常见工作流（状态概览、诊断、优化等）
• 所有 HTTP 传输方式均支持 Bearer 令牌身份验证
• 四种传输模式：stdio、SSE、Streamable HTTP 和 server（SSE + Streamable HTTP 组合）
• 通过环境变量自动连接

要求

• Python 3.10+
• 可通过本地网络访问的 GoodWe 逆变器（UDP 端口 8899 或 Modbus/TCP 端口 502）

安装

# with uv (recommended) — installs the locked dependency set from uv.lock
uv sync

# or a plain (editable) install
uv pip install -e .

使用方法

stdio（Claude Desktop）

goodwe-mcp

添加到 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "goodwe": {
      "command": "goodwe-mcp",
      "env": {
        "GOODWE_HOST": "192.168.1.100"
      }
    }
  }
}

SSE 传输

goodwe-mcp --transport sse --port 8080
# Server listens on http://0.0.0.0:8080/sse

Streamable HTTP 传输

goodwe-mcp --transport streamable-http --port 8080
# Server listens on http://0.0.0.0:8080/mcp

Server 传输（SSE + Streamable HTTP 组合）

在单个端口上同时提供两种传输方式——适用于需要同时支持旧版 SSE 客户端和现代 Streamable HTTP 客户端的场景。

goodwe-mcp --transport server --host 0.0.0.0 --port 8080
# SSE:             http://0.0.0.0:8080/sse  (GET) and /messages/ (POST)
# Streamable HTTP: http://0.0.0.0:8080/mcp

选项

--transport {stdio,sse,streamable-http,server}   Transport mode (default: stdio)
--host HOST                                      Bind address for SSE/HTTP (default: 127.0.0.1)
--port PORT                                      Listen port for SSE/HTTP (default: 8000)
--log-level {DEBUG,INFO,WARNING,ERROR}           Logging verbosity (default: INFO)
--auth-token TOKEN                               Bearer token required on all HTTP requests (env: MCP_AUTH_TOKEN)
--base-url URL                                   Public base URL, e.g. https://mcp.example.com (env: MCP_BASE_URL)
--allowed-hosts HOSTS                            Comma-separated Host header values to accept (env: MCP_ALLOWED_HOSTS)
--allowed-origins ORIGINS                        Comma-separated Origin header values to accept (env: MCP_ALLOWED_ORIGINS)

环境变量

变量	描述	默认值
GOODWE_HOST	启动时自动连接所用的逆变器 IP / 主机名	—
GOODWE_PORT	逆变器 UDP/TCP 端口	8899
GOODWE_FAMILY	覆盖逆变器系列（ET、EH、BT、BH、ES、EM、BP、DT、MS、NS、XS）	自动检测
MCP_AUTH_TOKEN	所有 HTTP 请求都必须提供的 Bearer 令牌	—（禁用身份验证）
MCP_BASE_URL	服务的公开基础 URL（用作 OAuth 颁发者 URL）	http://<host>:<port>
MCP_ALLOWED_HOSTS	以逗号分隔的可接受 Host 标头值；在非环回地址上绑定时启用 DNS 重绑定防护	—（仅在环回地址上绑定时启用防护）
MCP_ALLOWED_ORIGINS	以逗号分隔的可接受 Origin 标头值（基于浏览器的客户端）	—
MCP_PORT	容器默认命令和健康检查使用的监听端口（仅限 Docker）	8000

身份验证

所有 HTTP 传输方式（sse、streamable-http、server）均支持 Bearer 令牌身份验证。 启用后，每个 MCP 请求都必须包含 Authorization: Bearer <token> 标头。 /health 端点始终不受保护，因此 Kubernetes 探针可以继续正常工作。

通过环境变量启用（推荐）

export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
goodwe-mcp --transport server --host 0.0.0.0 --port 8080

通过 CLI 标志启用

goodwe-mcp --transport streamable-http --port 8080 --auth-token my-secret-token

Claude Desktop / MCP 客户端配置

将令牌添加到客户端的 MCP 服务配置中。例如，在 Claude Desktop 中通过注入标头的代理使用 streamable-http 传输，或用于任何支持 Authorization 标头的客户端：

{
  "mcpServers": {
    "goodwe": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer my-secret-token"
      }
    }
  }
}

Docker / Docker Compose

通过环境变量传递令牌：

MCP_AUTH_TOKEN=my-secret-token GOODWE_HOST=192.168.1.100 \
  docker compose -f docs/docker-compose.yml up -d

Kubernetes

在应用清单之前，在 docs/k8s/secret.yaml 中设置令牌：

stringData:
  GOODWE_HOST: "192.168.1.100"
  MCP_AUTH_TOKEN: "my-secret-token"

如果 MCP_AUTH_TOKEN 为空或未设置，则会禁用身份验证，所有 HTTP 端点均可公开访问。当服务绑定到非环回地址且未设置令牌时，服务将在启动时记录警告。

DNS 重绑定防护

当 MCP SDK 服务器绑定到环回地址时，会自动验证 Host 和 Origin 标头。对于其他任何绑定地址（包括 Docker 默认的 0.0.0.0），请列出客户端用于合法访问服务器的主机名或 host:port 对：

MCP_ALLOWED_HOSTS="mcp.example.com,192.168.1.10:8000" \
  goodwe-mcp --transport server --host 0.0.0.0 --port 8000

Host 标头未列出的请求会被拒绝，并返回 HTTP 421。:* 后缀可匹配任意端口（例如 192.168.1.10:*）。使用 MCP_ALLOWED_ORIGINS 可额外允许来自指定来源的浏览器客户端。服务器绑定到非环回地址且未设置此项时，会在启动时记录警告。

TLS / HTTPS

MCP 服务本身不会终止 TLS。对于任何非 localhost 部署，请在其前方放置一个负责终止 TLS 的反向代理（nginx、Caddy、Traefik）。通过纯 HTTP 提供逆变器数据（当与家庭关联时，这属于 GDPR 定义的个人数据）存在安全风险。

Caddy 示例（最简单的方案）：

mcp.example.com {
    reverse_proxy localhost:8000
}

数据处理声明

此服务器会处理 GoodWe 太阳能逆变器的数据，包括逆变器的 IP 地址、序列号和能耗指标。在家庭中部署并由房主出于个人用途运行时，此类处理属于 GDPR 家庭豁免范围（第 2(2)(c) 条），GDPR 不适用。如果用于商业部署，例如监控属于第三方客户的逆变器，运营方将成为 GDPR（EU）2016/679 规定的数据控制者，必须为数据处理确立合法依据（第 6 条）、保存数据处理活动记录（第 30 条），并确保采取适当的技术和组织措施（第 32 条），包括 TLS 加密和访问控制。

Docker

构建

针对当前机器的架构进行构建：

docker build -t goodwe-inverter-mcp:latest .

多平台构建（amd64 + arm64）

使用 docker buildx 构建可在 x86-64 服务器和 ARM 设备（Raspberry Pi、Apple Silicon、AWS Graviton 等）上运行的镜像。

一次性设置 — 创建支持交叉编译的构建器：

docker buildx create --name multi --driver docker-container --bootstrap --use

构建两个平台并加载到本地守护进程 — 需要使用 containerd 镜像存储（Docker Desktop 4.34+ 默认启用；在 Linux 上运行 dockerd --snapshotter=overlayfs，或在 /etc/docker/daemon.json 中启用）：

docker buildx build --platform linux/amd64,linux/arm64 -t goodwe-inverter-mcp:latest --load .

构建两个平台并推送到镜像仓库（例如 Docker Hub 或 GHCR）：

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t youruser/goodwe-inverter-mcp:latest \
  --push .

构建两个平台并导出为本地 OCI tar 文件（无需镜像仓库）：

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t goodwe-inverter-mcp:latest \
  --output type=oci,dest=goodwe-inverter-mcp.tar .

运行

docker run -d \
  --name goodwe-mcp \
  -e GOODWE_HOST=192.168.1.100 \
  -p 8000:8000 \
  goodwe-inverter-mcp:latest

容器默认使用 --transport server（在端口 8000 上运行 SSE + Streamable HTTP）。

使用 MCP_PORT 更改端口，以确保内置健康检查也使用新端口：

docker run -d -e GOODWE_HOST=192.168.1.100 -e MCP_PORT=9000 -p 9000:9000 \
  goodwe-inverter-mcp:latest

要更改传输方式，请覆盖命令。请确保 MCP_PORT 与之同步，因为健康检查会探测该端口：

docker run -d -e GOODWE_HOST=192.168.1.100 -e MCP_PORT=9000 -p 9000:9000 \
  goodwe-inverter-mcp:latest \
  goodwe-mcp --transport streamable-http --host 0.0.0.0 --port 9000

Docker Compose

GOODWE_HOST=192.168.1.100 docker compose -f docs/docker-compose.yml up -d

docs/docker-compose.yml 默认使用 network_mode: host，以便容器访问本地局域网中的逆变器。如果你的网络已将局域网流量路由到容器，请删除该行。

Kubernetes

前提条件

GoodWe 逆变器通过本地网络上的 UDP/TCP 进行通信。Pod 需要能够访问逆变器的 IP。最简单的配置是在同一子网中的节点上设置 hostNetwork: true；如果集群采用扁平网络或有其他路由方案，则可删除此项。

部署

# 1. Edit the inverter IP
vi docs/k8s/secret.yaml

# 2. Apply all manifests
kubectl apply -f docs/k8s/

# 3. Check status
kubectl rollout status deployment/goodwe-mcp
kubectl logs -f deployment/goodwe-mcp

健康检查端点

存活探针和就绪探针都会请求 GET /health，该端点返回：

{ "status": "ok", "inverter_connected": true }

HTTP 服务器启动后，Pod 即变为就绪状态。服务器成功连接到逆变器之前，inverter_connected 会一直为 false（首次 MCP 客户端会话时会触发自动连接）。

工具

工具	描述
connect_inverter	通过 IP/主机连接 GoodWe 逆变器
get_connection_status	检查是否已连接并显示设备信息
get_device_info	型号名称、序列号、固件版本
get_runtime_data	所有实时传感器值（可按类型筛选：PV/AC/BAT/GRID/UPS/BMS）
list_sensors	列出所有传感器 ID 和名称
read_sensor	按 ID 读取单个传感器
get_settings_data	所有可配置设置及其当前值
read_setting	按 ID 读取单个设置
write_setting	为可配置设置写入一个值
get_operation_mode	当前模式和支持的模式
set_operation_mode	设置模式：general、eco、backup、off_grid、peak_shaving、eco_charge、eco_discharge
get_grid_export_limit	电网输出功率上限，单位为瓦
set_grid_export_limit	设置电网输出功率上限（0 = 已禁用）
get_battery_dod	电池放电深度设置
set_battery_dod	设置电池放电深度（0–99%）

提示词

预先编写的提示词模板，MCP 客户端可以获取并直接使用。

提示词	参数	描述
status_overview	—	完整状态报告：连接、实时功率流、电池、电网
battery_optimisation	—	检查电池设置并建议改进放电深度／模式
grid_export_config	—	检查并调整电网输出功率上限
operation_mode_change	—	说明可用模式并帮助切换到合适的模式
diagnose_issue	symptom（可选）	收集完整诊断信息并识别问题
daily_energy_summary	—	以易读表格显示今日能量计数器数据

资源

URI	描述
inverter://status	连接状态和设备信息（JSON）
inverter://runtime	所有实时传感器值（JSON）
inverter://settings	所有可配置设置（JSON）
inverter://power/now	实时功率流——PV、电池、电网和负载（单位为瓦），按类型分组
inverter://energy/today	今日能量计数器数据——发电量、负载、电网购电／售电、电池充电／放电（kWh）
inverter://battery	在一个数据载荷中提供电池传感器、放电深度限制和当前运行模式
inverter://sensors	静态传感器目录——每个传感器的 ID、名称、单位和类型（无实时值）

逆变器系列

系列	型号	说明
ET / EH / BT / BH	混合型三相	支持电池，最多 4 个 PV 组串
ES / EM / BP	混合型单相	支持电池
DT / MS / NS / XS	仅并网	不支持电池

开发

# install runtime + dev dependencies from the lockfile
uv sync

# run the test suite
uv run pytest

# with a coverage report
uv run pytest --cov=goodwe_mcp --cov-report=term-missing

# lint
uv run ruff check src tests

测试完全使用内存中的模拟逆变器运行，因此不需要硬件或网络访问。测试通过真实的 MCP 客户端会话和实际的 ASGI 应用驱动服务，涵盖工具输入验证、资源数据载荷、Bearer 身份验证、DNS 重绑定防护和 CLI。GitHub Actions 会在 Python 3.10 至 3.13 上运行测试套件，并在每次推送和拉取请求时构建容器映像。

许可证

请参阅代码库根目录中的 LICENSE 文件。

免责声明

本软件与 GoodWe Inc. 无关，也未获其认可。使用风险由您自行承担。 本软件是我利用业余时间维护的个人项目。 更多信息请参阅许可证。