Growatt MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Growatt MCP Server How much energy did my solar panels generate today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Growatt MCP Server
An MCP server that lets AI assistants (Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI and any other MCP client) read and control a Growatt solar installation through the official Growatt ShineServer Public API.
Ask things like "how much did my panels generate today?", "what is the battery SOC?", "compare today with yesterday hour by hour", or "set the discharge cut-off to 15%", and the assistant calls the right endpoint for you.
Complete API coverage. All 27 documented endpoints are implemented and exposed as 26 tools.
Contract-tested. Every request is verified against a pinned endpoint contract, so upstream changes are caught by CI, not by users.
Typed, tested, linted.
mypy --strict, 130+ tests, ruff, pip-audit, and a server start-up smoke test on Python 3.11 to 3.13.Safe by design. State-changing tools carry MCP
readOnlyHint=false/destructiveHint=trueannotations and can be disabled withGROWATT_READ_ONLY=1. Errors from Growatt come back as structured JSON the assistant can read.
Table of contents
Related MCP server: anker-solix-mcp
Tools
Tools marked writes change state on Growatt's side. They are annotated as non-read-only so MCP clients can ask for confirmation, and they disappear entirely when the server runs with GROWATT_READ_ONLY=1.
Plants (power stations)
Tool | Endpoint | Description |
|
| Plants visible to the account |
|
| Name, location, peak power, timezone |
|
| Today's / monthly / yearly / total energy, current power |
|
| Daily, monthly or yearly history (max 7 days per call) |
|
| Plants of a specific end user |
|
| Create a plant for an end user |
|
| Rename a plant or change its currency |
Devices
Tool | Endpoint | Description |
|
| Devices of a plant, or all devices paginated |
|
| Model, firmware, configured settings |
|
| Real-time PV, load, grid, battery SOC, temperatures, faults |
|
| Five-minute readings for one day |
|
| Device type and registration status of a serial |
|
| ShineWiFi / ShineLAN sticks on a plant |
|
| Attach a datalogger to a plant |
|
| Attach a storage device to a plant |
Control
Tool | Endpoint | Description |
|
| Switch a device on or off |
|
| Active power limit (percent, or watts for NOAH/NEXA) |
|
| Read a VPP parameter, e.g. discharge cut-off SOC |
|
| Write a VPP parameter or time schedule |
MAX-series inverters
Tool | Endpoint | Description |
|
| Latest data for one MAX inverter |
|
| Latest data for several MAX inverters |
|
| Write a register on a MAX inverter |
Users (installer / distributor accounts)
Tool | Endpoint | Description |
|
| End-user accounts managed by this account |
|
| Whether a user name exists |
|
| Create an end-user account |
|
| Update an end-user's mobile number |
Requirements
Python 3.11 or newer
uv (recommended) or pip
A Growatt account with at least one plant, and an API token
Getting a Growatt API token
The token is issued in the ShinePhone mobile app (the same app you use to monitor the plant). No developer registration is needed.
Open ShinePhone, log in with your Growatt account and tap Me in the bottom bar.
On the Me screen, tap your username at the top.
In the profile, tap API Token (last row).
Tap the copy icon next to the token value.
Make sure Use Status is switched on, otherwise the API rejects the token.
Step 1 | Step 2 | Step 3 | Steps 4–5 |
|
|
|
|
Screenshots show Growatt's ShinePhone app and are used for illustration only.
Keep the token private: it grants full read and write access to your installation, including inverter settings. If it leaks, open the same screen and tap Reopen to issue a new one.
Installation
git clone https://github.com/ratoshniuk/growatt-mcp-server.git growatt-mcp
cd growatt-mcp
uv syncQuick check that the server starts (it speaks MCP over stdio, so it waits for input; press Ctrl+C to exit):
GROWATT_TOKEN=your_token uv run growatt-mcp
uv run growatt-mcp --versionIf the token is missing the server exits with code 2 and explains where to get one.
Without uv:
python -m venv .venv
source .venv/bin/activate
pip install -e .
GROWATT_TOKEN=your_token growatt-mcpConnecting to an MCP client
The server speaks MCP over stdio, so it works with any MCP-capable client. There are two ways to launch it:
From a local clone (recommended if you want to edit the code):
uv --directory /absolute/path/to/growatt-mcp run growatt-mcpStraight from GitHub, no clone (uvx downloads and caches it):
uvx --from git+https://github.com/ratoshniuk/growatt-mcp-server growatt-mcp
The examples below use the local-clone form. To use the no-clone form, replace "command": "uv" with "command": "uvx" and the args with ["--from", "git+https://github.com/ratoshniuk/growatt-mcp-server", "growatt-mcp"]. Some GUI clients don't inherit your shell PATH; if the server fails to start, use the full path from which uv or which uvx.
Restart the client after saving its configuration.
Claude Code
claude mcp add growatt \
-e GROWATT_TOKEN=your_token \
-- uv --directory /absolute/path/to/growatt-mcp run growatt-mcpAdd -s user to make it available in every project instead of only the current one.
Claude Desktop
Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"growatt": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"],
"env": {
"GROWATT_TOKEN": "your_token"
}
}
}
}Cursor
Settings → MCP → Add new global MCP server, or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Same format as Claude Desktop:
{
"mcpServers": {
"growatt": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"],
"env": { "GROWATT_TOKEN": "your_token" }
}
}
}VS Code (GitHub Copilot agent mode)
Create .vscode/mcp.json in your workspace, or run MCP: Add Server from the command palette. VS Code can prompt for the token so it is not stored in plain text:
{
"inputs": [
{ "id": "growatt-token", "type": "promptString", "description": "Growatt API token", "password": true }
],
"servers": {
"growatt": {
"type": "stdio",
"command": "uv",
"args": ["--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"],
"env": { "GROWATT_TOKEN": "${input:growatt-token}" }
}
}
}Windsurf
Edit ~/.codeium/windsurf/mcp_config.json (or Settings → Cascade → MCP Servers → Manage):
{
"mcpServers": {
"growatt": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"],
"env": { "GROWATT_TOKEN": "your_token" }
}
}
}Cline (VS Code extension)
Open the MCP Servers panel → Configure MCP Servers, which opens cline_mcp_settings.json:
{
"mcpServers": {
"growatt": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"],
"env": { "GROWATT_TOKEN": "your_token" },
"disabled": false
}
}
}Zed
Add to ~/.config/zed/settings.json:
{
"context_servers": {
"growatt": {
"source": "custom",
"command": "uv",
"args": ["--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"],
"env": { "GROWATT_TOKEN": "your_token" }
}
}
}OpenAI Codex CLI
Codex uses TOML. Add to ~/.codex/config.toml:
[mcp_servers.growatt]
command = "uv"
args = ["--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"]
env = { GROWATT_TOKEN = "your_token" }Gemini CLI
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"growatt": {
"command": "uv",
"args": ["--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"],
"env": { "GROWATT_TOKEN": "your_token" }
}
}
}OpenCode
This repository ships an opencode.json, so launching opencode from a clone picks the server up automatically. It reads the token from the GROWATT_TOKEN environment variable. For a global setup, add the same block to ~/.config/opencode/opencode.json:
{
"mcp": {
"growatt": {
"type": "local",
"command": ["uv", "--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"],
"environment": { "GROWATT_TOKEN": "your_token" }
}
}
}Continue
Add to ~/.continue/config.yaml:
mcpServers:
- name: growatt
command: uv
args: ["--directory", "/absolute/path/to/growatt-mcp", "run", "growatt-mcp"]
env:
GROWATT_TOKEN: your_tokenAny other client, or testing without a client
Point the client at the stdio command above. To poke at the tools interactively, use the MCP Inspector:
GROWATT_TOKEN=your_token npx @modelcontextprotocol/inspector \
uv --directory /absolute/path/to/growatt-mcp run growatt-mcpConfiguration
Variable | Required | Default | Description |
| yes | ShinePhone API token | |
| no |
| Picks the regional API host: |
| no | Explicit API host (https only); overrides | |
| no |
| HTTP timeout in seconds |
| no |
| Set to |
Example prompts
"List my plants and show today's generation."
"Get the latest data from inverter YOUR_DEVICE_SN (type
min) and tell me the battery SOC and grid import.""Fetch the 5-minute history for today and yesterday and compare hourly PV, load and battery charge."
"Read
set_param_23on my inverter." (discharge cut-off SOC)"Which dataloggers are attached to plant 123?"
Notes and gotchas
Device types. Most tools need a
device_typesuch asmin,sph,spa,max,inv,wit,tlx.get_devicesreturns the right value for each device.Timestamps in history data. The
calendarfield is a Unix epoch built from the plant's local wall-clock interpreted as UTC+8. To get local time, treat the epoch as UTC and add 8 hours."Today" counters undercount at night. Fields like
etoUserTodayonly accumulate while the inverter is running. On hybrid systems that idle overnight at the battery cut-off SOC, grid import from the meter is still visible inpacToUserTotalof the 5-minute history, so integrate that series for a true figure.Errors are data. When a call fails, the tool returns
{"error": {"type": "api" | "http" | "transport" | "client", ...}}instead of raising, so the assistant can explain what went wrong. Non-JSON HTTP error bodies are not forwarded.Rate limits. The Growatt API throttles aggressive polling. Prefer
get_device_history(one call per day) over repeatedget_device_last_data.Date ranges.
get_plant_energyaccepts at most 7 days per request; page through for longer periods.
API version and contract testing
Growatt does not publish version numbers for the ShineServer Public API, and there is no endpoint that reports which revision a server runs. This project pins the contract instead:
API | Growatt ShineServer Public API (v1 and v4 "new-api" endpoints) |
Documented by | community-maintained Postman collection ShineServer Public (workspace |
Captured | 2026-09-21 |
Fixture |
|
Pinned in |
|
Coverage | 27 endpoints in the contract, 27 implemented, exposed as 26 tools |
tests/contract/test_api_contract.py sends every client method through a mock transport and checks that its HTTP method, path, and parameter names and placement (query string vs form body) exist in the contract. It also fails if the contract contains an endpoint the client does not implement, if the client has a method the test table does not cover, or if the fixture changes without the pin being updated.
To adopt a newer collection, follow CONTRIBUTING.md; the failing tests report exactly which endpoints or parameters changed.
Official Growatt resources
Growatt: https://en.growatt.com/
ShineServer monitoring platform: https://server.growatt.com/
ShinePhone app (where the API token is issued): iOS App Store and Google Play, search "ShinePhone"
API documentation (linked from Growatt's Postman collection): https://www.showdoc.com.cn/2598832417617967/11558377939801334
Regional API hosts:
https://openapi.growatt.com(global / Europe),https://openapi-cn.growatt.com(China),https://openapi-us.growatt.com(North America)Growatt platform terms: https://openapi.growatt.com/userTerms/termsOfUse_en.html
Community Postman workspace "Growatt Public" (the source of the endpoint contract): https://www.postman.com/gold-water-163355/workspace/growatt-public
Project layout
src/growatt_mcp/
__init__.py package version and public exports
__main__.py python -m growatt_mcp
config.py Settings from GROWATT_* environment variables
server.py create_app(), CLI entry point
api/ async client for the Growatt API
http.py auth header, JSON decoding, error translation
errors.py GrowattError, GrowattHTTPError, GrowattAPIError
client.py GrowattClient facade: .users .plants .devices .control .max
users.py, plants.py, devices.py, control.py, max_inverters.py one class per endpoint group
contract.py pinned API contract (Postman id, date, SHA-256)
tools/ MCP tools, one module per endpoint group
_common.py Registrar (read/write annotations, read-only mode), shared parameter types, error-to-JSON wrapper
plants.py, devices.py, control.py, max_inverters.py, users.py
tests/
conftest.py recording mock transport, client and app fixtures
unit/ config, server, api/*, tools/*
contract/ client requests vs the pinned Postman collection
fixtures/ endpoint contract (methods, paths, parameter names)
scripts/
derive_contract.py regenerates the fixture from a Postman exportThe client is usable on its own, without MCP:
from growatt_mcp import GrowattClient
async with GrowattClient(token) as client:
plants = await client.plants.list()
latest = await client.devices.last_data("YOUR_DEVICE_SN", "min")Development
uv sync --group dev
uv run growatt-mcp # run the server
uv run ruff check . # lint
uv run ruff format . # format
uv run mypy # type check (strict)
uv run pytest # testsCI runs lint, format check, mypy, tests, a server start-up smoke test on Python 3.11, 3.12 and 3.13, and pip-audit for every push and pull request. GitHub Actions are pinned to commit SHAs and Dependabot keeps them and the lockfile current. See CONTRIBUTING.md and CHANGELOG.md.
Disclaimer
This is an independent, community project. It is not affiliated with, endorsed by, or supported by Growatt. Growatt, ShineServer and ShinePhone are trademarks of Shenzhen Growatt New Energy Co., Ltd. Use of the Growatt Public API is subject to Growatt's terms. Commands that change inverter settings are executed at your own risk. See SECURITY.md for the threat model and how to report issues.
License
MIT © Maksym Ratoshniuk
Available Tools
26 toolsadd_dataloggerADestructive
Attach a datalogger to a plant. Changes state on Growatt's side.
Inputs: sn (required), plant_id (required), c_user_id (required). Returns: result
add_plantADestructive
Create a new plant for an end user. Changes state on Growatt's side.
Inputs: name (required), c_user_id (required), peak_power (required). Returns: result
add_storage_deviceADestructive
Attach a storage (battery) device to a plant. Changes state on Growatt's side.
Inputs: sn (required), plant_id (required), c_user_id (required). Returns: result
check_device_snARead-onlyIdempotent
Look up a serial number to learn its device type and whether it is already registered.
Inputs: sn (required). Returns: result
check_userBRead-onlyIdempotent
Check whether a Growatt user name exists.
Inputs: user_name (required). Returns: result
get_dataloggersARead-onlyIdempotent
List the dataloggers (ShineWiFi / ShineLAN sticks) attached to a plant.
Inputs: plant_id (required). Returns: result
get_device_historyARead-onlyIdempotent
Get five-minute readings for a single device for one day.
The "calendar" field is an epoch built from the plant's local wall-clock interpreted as UTC+8; treat it as UTC and add 8 hours to get local time.
Inputs: date (required), device_sn (required), device_type (required). Returns: result
get_device_infoARead-onlyIdempotent
Get static information for a device: model, firmware, configured settings.
Inputs: device_sn (required), device_type (required). Returns: result
get_device_last_dataARead-onlyIdempotent
Get the latest real-time reading: PV power, load, grid import/export, battery SOC, temperatures, faults.
Inputs: device_sn (required), device_type (required). Returns: result
get_devicesARead-onlyIdempotent
List devices with their type ("min", "sph", "max", ...), which the other tools need.
With a plant_id, returns every device of that plant (page is ignored). Without it, returns all devices on the account, paginated.
Inputs: page, plant_id. Returns: result
get_max_batch_dataARead-onlyIdempotent
Get the latest data for several MAX-series inverters in one call.
Inputs: device_sns (required), page_num. Returns: result
get_max_dataARead-onlyIdempotent
Get the latest data for one MAX-series inverter.
Inputs: device_sn (required). Returns: result
get_plant_dataARead-onlyIdempotent
Get the current energy overview for a plant: today's, monthly, yearly and total energy, current power.
Inputs: plant_id (required). Returns: result
get_plant_detailsARead-onlyIdempotent
Get basic information about a plant: name, location, peak power, timezone.
Inputs: plant_id. Returns: result
get_plant_energyARead-onlyIdempotent
Get historical energy generation for a plant.
Inputs: end_date (required), plant_id (required), start_date (required), page, +2 more. Returns: result
get_plantsARead-onlyIdempotent
List all plants (solar installations) visible to this Growatt account.
Inputs: no named parameters. Returns: result
get_user_plantsARead-onlyIdempotent
List the plants that belong to a specific end user (installer / distributor accounts).
Inputs: user_name (required). Returns: result
list_usersARead-onlyIdempotent
List end-user accounts managed by this Growatt account.
Inputs: page, perpage. Returns: result
modify_plantADestructive
Rename a plant and/or change its currency. Changes state on Growatt's side.
Inputs: plant_id (required), c_user_id (required), name, currency. Returns: result
modify_userADestructive
Update an end-user's mobile number. Changes state on Growatt's side.
Inputs: mobile (required), c_user_id (required). Returns: result
read_device_parameterBRead-onlyIdempotent
Read a VPP (Virtual Power Plant) parameter from a device.
Inputs: set_type (required), device_sn (required), device_type (required). Returns: result
register_userADestructive
Create an end-user account under this Growatt account. Changes state on Growatt's side.
Inputs: user_name (required), user_type (required), user_email (required), user_country (required), +1 more. Returns: result
set_device_on_offADestructive
Turn a device on or off. Changes state on Growatt's side.
Inputs: turn_on (required), device_sn (required), device_type (required). Returns: result
set_device_parameterBDestructive
Write a VPP (Virtual Power Plant) parameter on a device. Changes state on Growatt's side.
Inputs: value (required), set_type (required), device_sn (required), device_type (required), +1 more. Returns: result
set_device_powerADestructive
Set the active power limit of a device. Changes state on Growatt's side.
Inputs: value (required), device_sn (required), device_type (required). Returns: result
set_max_parameterBDestructive
Write a setting on a MAX-series inverter. Changes state on Growatt's side.
Inputs: values (required), device_sn (required), setting_type (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Most tools have distinct targets: plant details, plant data, plant energy, device info, dataloggers, users, and MAX-series inverters are clearly separated. A few pairs like get_plant_details vs get_plant_data and get_device_last_data vs get_max_data could be confused, but the descriptions disambiguate them well enough.
The dominant get_* pattern is clear, but there is a mix of list_users, check_user, read_device_parameter, add_*, set_*, modify_*, and register_user. The inconsistent use of list vs get for listing resources and get vs read vs check makes the naming readable but not fully predictable.
At 26 tools, the server is beyond the 25-tool threshold for a heavy surface. It covers many subdomains, but the count is high enough that agents will need to filter through many similar-looking operations.
The server covers plant creation/modification, device monitoring and control, user management, and MAX-specific operations. Notable lifecycle gaps exist: there are no remove/delete operations for plants, users, dataloggers, or storage devices, and some user update coverage is minimal.
Maintenance
Related MCP Connectors
Home energy for AI assistants: live Power flow, Energy history, solar forecast, and device control.
Read-only solar inverter monitoring (SolarEdge, Enphase, Huawei, Fronius): plants, energy, alarms.
Ask about your home solar station: power, battery, outages and history. Changes need your approval.
Paid Solar, Battery & Distributed Energy Intelligence API via x402. Unpaid tool calls return 402.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI assistants to monitor and control Tesla Powerwall 2 systems via local gateway API.18MIT
- AlicenseAqualityCmaintenanceEnables LLM agents to query live data from Anker Solix solar systems (Solarbank, expansion batteries, Smartmeter) via natural language, such as current solar production or battery state of charge.121MIT
- AlicenseAqualityDmaintenanceProvides real-time access to solar inverter data from the SolaX Cloud API, enabling queries of power output, energy yields, battery status, and grid import/export data.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables conversational home power management by providing real-time solar, battery, and grid status, plus forecasts to answer questions like whether you can run an appliance. It supports Victron and Growatt inverters, remembers household appliances and grid events, and renders an interactive dashboard card in MCP-compatible clients.MIT



