GoodWe MCP Server

GoodWe逆變器的MCP伺服器實作

文件

GoodWe Inverter MCP Server

MCP server for monitoring and controlling GoodWe solar inverters over the local network.

Built on the goodwe library and the Model Context Protocol Python SDK.

Based on the Home Assistant GoodWe integration — the sensor definitions, operation modes, settings, and inverter family support are modelled directly after that implementation.

Features

Read live runtime data: PV production, battery state, grid import/export, load consumption
Read and write all configurable inverter settings
Switch operation modes (general, eco, backup, peak-shaving, off-grid, …)
Control grid export limit and battery depth-of-discharge
7 MCP resources: status, runtime, settings, power flow, daily energy, battery, sensor catalog
6 built-in prompt templates for common workflows (status overview, diagnostics, optimisation, …)
Bearer token authentication for all HTTP transports
Four transport modes: stdio, SSE, Streamable HTTP, and server (SSE + Streamable HTTP combined)
Auto-connect via environment variables

Requirements

Python 3.10+
GoodWe inverter reachable on the local network (UDP port 8899 or Modbus/TCP port 502)

Installation

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

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

Usage

stdio (Claude Desktop)

goodwe-mcp

Add to ~/.claude/claude_desktop_config.json:

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

SSE transport

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

Streamable HTTP transport

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

Server transport (SSE + Streamable HTTP combined)

Serves both transports on a single port — useful when you need to support legacy SSE clients and modern Streamable HTTP clients simultaneously.

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

Options

--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)

Environment variables

Variable	Description	Default
`GOODWE_HOST`	Inverter IP / hostname for auto-connect on startup	—
`GOODWE_PORT`	Inverter UDP/TCP port	`8899`
`GOODWE_FAMILY`	Inverter family override (ET, EH, BT, BH, ES, EM, BP, DT, MS, NS, XS)	auto-detect
`MCP_AUTH_TOKEN`	Bearer token required on all HTTP requests	— (auth disabled)
`MCP_BASE_URL`	Public base URL of the server (used as OAuth issuer URL)	`http://<host>:<port>`
`MCP_ALLOWED_HOSTS`	Comma-separated `Host` header values to accept; enables DNS-rebinding protection on non-loopback binds	— (protection only on loopback binds)
`MCP_ALLOWED_ORIGINS`	Comma-separated `Origin` header values to accept (browser-based clients)	—
`MCP_PORT`	Listen port used by the container's default command and health check (Docker only)	`8000`

Authentication

Bearer token authentication is supported for all HTTP transports (sse, streamable-http, server). When enabled, every MCP request must include an Authorization: Bearer <token> header. The /health endpoint is always unprotected so Kubernetes probes continue to work.

Enable via environment variable (recommended)

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

Enable via CLI flag

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

Claude Desktop / MCP client configuration

Add the token to your client's MCP server configuration. For example, with Claude Desktop using the streamable-http transport via a proxy that injects the header, or with any client that supports Authorization headers:

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

Docker / Docker Compose

Pass the token through the environment:

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

Kubernetes

Set the token in docs/k8s/secret.yaml before applying the manifests:

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

If MCP_AUTH_TOKEN is empty or not set, authentication is disabled and all HTTP endpoints are publicly accessible. The server will log a warning at startup when bound to a non-loopback address without a token.

DNS rebinding protection

The MCP SDK validates the Host and Origin headers automatically when the server is bound to a loopback address. For any other bind address (including the Docker default 0.0.0.0), list the hostnames or host:port pairs that clients legitimately use to reach the server:

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

Requests whose Host header is not listed are rejected with HTTP 421. A :* suffix matches any port (e.g. 192.168.1.10:*). Use MCP_ALLOWED_ORIGINS to additionally allow browser-based clients from specific origins. The server logs a warning at startup when bound to a non-loopback address without this setting.

TLS / HTTPS

The MCP server itself does not terminate TLS. For any non-localhost deployment, place a TLS-terminating reverse proxy in front of it (nginx, Caddy, Traefik). Serving inverter data — which constitutes personal data under GDPR when linked to a household — over plain HTTP is a security risk.

Example with Caddy (simplest option):

mcp.example.com {
    reverse_proxy localhost:8000
}

Data Processing Notice

This server processes data from a GoodWe solar inverter, including the inverter's IP address, serial number, and energy consumption metrics. When deployed in a home and operated by the homeowner for personal use, this processing falls under the GDPR household exemption (Art. 2(2)(c)) and GDPR does not apply. If deployed commercially — for example to monitor inverters belonging to third-party customers — the operator becomes a data controller under GDPR (EU) 2016/679 and must establish a lawful basis for processing (Art. 6), maintain records of processing activities (Art. 30), and ensure appropriate technical and organisational measures (Art. 32), including TLS encryption and access control.

Docker

Build

Build for the current machine's architecture:

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

Multi-platform builds (amd64 + arm64)

Use docker buildx to produce an image that runs on both x86-64 servers and ARM boards (Raspberry Pi, Apple Silicon, AWS Graviton, etc.).

One-time setup — create a builder that supports cross-compilation:

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

Build both platforms and load into the local daemon — requires the containerd image store (enabled by default in Docker Desktop 4.34+; on Linux run dockerd --snapshotter=overlayfs or enable it in /etc/docker/daemon.json):

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

Build both platforms and push to a registry (e.g. Docker Hub or GHCR):

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

Build both platforms and export as a local OCI tar (no registry needed):

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

Run

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

The container defaults to --transport server (SSE + Streamable HTTP on port 8000).

Change the port with MCP_PORT so the built-in health check follows it:

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

To change the transport, override the command. Keep MCP_PORT in sync, since the health check probes it:

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 uses network_mode: host by default so the container can reach the inverter on the local LAN. Remove that line if your network already routes LAN traffic into containers.

Kubernetes

Prerequisites

The GoodWe inverter communicates over UDP/TCP on the local network. The pod needs to reach the inverter's IP. The simplest setup is hostNetwork: true on a node in the same subnet; remove it if your cluster has flat networking or another routing solution.

Deploy

# 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

Health endpoints

Both liveness and readiness probes hit GET /health, which returns:

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

The pod becomes ready once the HTTP server is up. inverter_connected will be false until the server successfully connects to the inverter (auto-connect fires on the first MCP client session).

Tools

Tool	Description
`connect_inverter`	Connect to a GoodWe inverter by IP/host
`get_connection_status`	Check if connected and show device info
`get_device_info`	Model name, serial number, firmware version
`get_runtime_data`	All live sensor values (optional filter by kind: PV/AC/BAT/GRID/UPS/BMS)
`list_sensors`	List all sensor IDs and names
`read_sensor`	Read a single sensor by ID
`get_settings_data`	All configurable settings and current values
`read_setting`	Read a single setting by ID
`write_setting`	Write a value to a configurable setting
`get_operation_mode`	Current mode and supported modes
`set_operation_mode`	Set mode: general, eco, backup, off_grid, peak_shaving, eco_charge, eco_discharge
`get_grid_export_limit`	Grid export limit in watts
`set_grid_export_limit`	Set grid export limit (0 = disabled)
`get_battery_dod`	Battery depth-of-discharge setting
`set_battery_dod`	Set battery depth-of-discharge (0–99%)

Prompts

Pre-written prompt templates that MCP clients can fetch and use directly.

Prompt	Arguments	Description
`status_overview`	—	Full status report: connection, live power flow, battery, grid
`battery_optimisation`	—	Review battery settings and suggest DoD / mode improvements
`grid_export_config`	—	Check and adjust the grid export power limit
`operation_mode_change`	—	Explain available modes and help switch to the right one
`diagnose_issue`	`symptom` (optional)	Collect full diagnostics and identify problems
`daily_energy_summary`	—	Today's energy counters as a human-readable table

Resources

URI	Description
`inverter://status`	Connection status and device info (JSON)
`inverter://runtime`	All live sensor values (JSON)
`inverter://settings`	All configurable settings (JSON)
`inverter://power/now`	Real-time power flow — PV, battery, grid and load in watts, grouped by kind
`inverter://energy/today`	Today's energy counters — production, load, grid buy/sell, battery charge/discharge (kWh)
`inverter://battery`	Battery sensors, DoD limit and current operation mode in one payload
`inverter://sensors`	Static sensor catalog — id, name, unit and kind for every sensor (no live values)

Inverter families

Family	Models	Notes
ET / EH / BT / BH	Hybrid 3-phase	Battery support, up to 4 PV strings
ES / EM / BP	Hybrid single-phase	Battery support
DT / MS / NS / XS	Grid-tie only	No battery

Development

# 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

Tests run entirely against an in-memory fake inverter, so no hardware or network access is needed. They drive the server through a real MCP client session and the actual ASGI apps, covering tool input validation, resource payloads, bearer authentication, DNS-rebinding protection and the CLI. GitHub Actions runs the suite on Python 3.10 through 3.13 and builds the container image on every push and pull request.

License

See LICENSE file in the root of the repository.

Disclaimer

This software is not affiliated with or endorsed by GoodWe Inc. Use at your own risk. This software is a personal project that I maintain in my free time. Refer to the licence for more information.