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

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

Prompts

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

Resources

Inverter families

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.