GoodWe MCP Server

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)
uv pip install .

# or editable install for development
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)

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

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.

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). Override the transport or port via CMD args:

docker run -d -e GOODWE_HOST=192.168.1.100 -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 |

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.