SolaX Cloud MCP Server

An MCP server that provides real-time access to solar inverter data from the SolaX Developer Platform API. Query your inverter's current power output, energy yields, battery status, and grid import/export data directly from Claude Code or Claude Desktop.

Prerequisites

• Python 3.10+ (automatically provisioned by uv)

• uv package manager (install here)

• A SolaX Developer Platform account with OAuth2 application registered

• Device (inverter) serial number (deviceSn) for your inverter

Related MCP server: EcoFlow MCP Server

Getting Started

1. Register an OAuth2 Application

1. Log in to SolaX Developer Platform

2. Navigate to Application section

3. Create a new application and enable client_credentials grant type

4. Copy your Client ID and Client Secret (keep these secret!)

2. Identify Your Device Serial Number

1. Log in to SolaX Developer Platform

2. Navigate to My Account or device management section

3. Find your inverter's device serial number (e.g., X3ABCD0123)

   • This is NOT the old WiFi dongle registration number used by the legacy SolaX Cloud API

3. Install the Server

# Clone or navigate to the repo
cd /Users/gary/mysrc/claude/solax-cloud-mcp

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies and create virtual environment
uv sync

4. Configure Credentials

# Copy the example environment file
cp .env.example .env

# Edit .env and fill in your credentials
nano .env

Add your OAuth2 credentials and device serial number:

SOLAX_CLIENT_ID=your_client_id
SOLAX_CLIENT_SECRET=your_client_secret
SOLAX_DEVICE_SN=X3ABCD0123

5. Register with Claude Code

To use this server with Claude Code or Claude Desktop:

claude mcp add solax-cloud \
  --env SOLAX_CLIENT_ID=your_client_id \
  --env SOLAX_CLIENT_SECRET=your_client_secret \
  --env SOLAX_DEVICE_SN=your_device_sn \
  --scope user \
  -- uv run --directory /Users/gary/mysrc/claude/solax-cloud-mcp solax-cloud-mcp

If the above doesn't work (environment variable propagation issues), edit your MCP config JSON directly:

• Claude Code: ~/.claude/mcp.json or project settings

• Claude Desktop: ~/.config/Claude/claude_desktop_config.json (macOS) or equivalent

Add this entry:

{
  "solax-cloud": {
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/Users/gary/mysrc/claude/solax-cloud-mcp",
      "solax-cloud-mcp"
    ],
    "env": {
      "SOLAX_CLIENT_ID": "your_client_id",
      "SOLAX_CLIENT_SECRET": "your_client_secret",
      "SOLAX_DEVICE_SN": "your_device_sn"
    }
  }
}

Usage

Once registered, the get_realtime_data tool is available in your MCP toolset. Use it to query real-time inverter data.

Tool: get_realtime_data

Arguments:

• device_sn (optional): Inverter device serial number. If omitted, defaults to SOLAX_DEVICE_SN environment variable.

Returns: A structured dictionary containing:

{
  "device": {
    "deviceSn": "X3ABCD0123",
    "registerNo": "SE123456SP",
    "dataTime": "2025-05-22 15:13:10",
    "plantLocalTime": "2025-05-22 15:13:10"
  },
  "status": {
    "code": 102,
    "description": "Normal"
  },
  "pv": [
    {"string": 1, "voltage_V": 421.7, "current_A": 0.4, "power_W": 189.0},
    {"string": 2, "voltage_V": 418.0, "current_A": 0.0, "power_W": 0.0}
  ],
  "mppt": {
    "trackers": [
      {"mppt": 1, "voltage_V": 0.0, "current_A": 0.0, "power_W": 0.0}
    ],
    "totalPower_W": null
  },
  "ac": {
    "phases": [
      {"phase": 1, "voltage_V": 224.1, "current_A": 0.9, "power_W": 189.0, "frequency_Hz": 50.0},
      {"phase": 2, "voltage_V": 226.5, "current_A": 0.8, "power_W": 171.0, "frequency_Hz": 50.0}
    ],
    "totalPower_W": 360.0,
    "totalReactivePower": 0,
    "powerFactor": 1.0,
    "gridFrequency": 50.0
  },
  "energy": {
    "dailyYield_kWh": 157.4,
    "totalYield_kWh": 20465.3,
    "dailyACOutput_kWh": 160.9,
    "totalACOutput_kWh": 19907.5
  },
  "meter1": {
    "gridPower_W": 0,
    "todayImportEnergy_kWh": 0.07,
    "totalImportEnergy_kWh": 23.28,
    "todayExportEnergy_kWh": 0.0,
    "totalExportEnergy_kWh": 64.98
  },
  "meter2": {
    "gridPower_W": 0,
    "todayImportEnergy_kWh": 0.08,
    "totalImportEnergy_kWh": 1.39,
    "todayExportEnergy_kWh": 0.0,
    "totalExportEnergy_kWh": 0.75
  },
  "battery": {
    "soc_percent": 85.5,
    "remainingEnergy_kWh": 1024.8,
    "soh_percent": 99.2,
    "chargeDischargePower_W": -150.5,
    "voltage_V": 409.6,
    "current_A": -15.2,
    "temperature_C": 28.3,
    "cycleTimes": 142,
    "totalCharge_kWh": 4250.75,
    "totalDischarge_kWh": 4100.25,
    "status": {"code": 1, "description": "Work"}
  },
  "eps": {
    "voltage_V": [0.0, 0.0, 0.0],
    "current_A": [0.0, 0.0, 0.0],
    "activePower_W": [0.0, 0.0, 0.0],
    "apparentPower_W": [0.0, 0.0, 0.0]
  },
  "temperature": {
    "inverter_C": 40.4
  },
  "misc": {
    "l1l2Voltage_V": null,
    "l2l3Voltage_V": null,
    "l1l3Voltage_V": null
  }
}

Example Usage in Claude

"What's the current power output of my solar inverter?"

Claude will call get_realtime_data() and report the results to you in human-friendly terms.

Docker: Build, Deploy & HTTP Consumption

For containerized deployment on Raspberry Pi or any Docker-enabled system, you can run the server in HTTP mode:

Build the Docker Image

# Build the image
docker build -t solax-cloud-mcp:latest .

# Verify the build
docker images | grep solax-cloud-mcp

Deploy with Docker Compose

Configure your environment variables first:

# Copy and edit the environment file
cp .env.example .env
nano .env

Fill in your SolaX credentials and generate a strong API key:

SOLAX_CLIENT_ID=your_client_id
SOLAX_CLIENT_SECRET=your_client_secret
SOLAX_DEVICE_SN=your_device_sn
HTTP_API_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")

Start the HTTP server:

# Build and start the container in the background
docker-compose up -d

# Check logs
docker-compose logs -f solax-http

# Verify it's running
curl http://localhost:8000/health

The server listens on port 8000 and is accessible at http://YOUR_PI_IP:8000.

Consume the HTTP API

All endpoints (except /health) require a bearer token in the Authorization header.

Health Check (no authentication)

curl http://192.168.1.100:8000/health

Response:

{"status": "ok"}

Get Real-Time Inverter Data

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_sn": "X3ABCD0123"}' \
  http://192.168.1.100:8000/api/realtime-data

Returns current power output, battery SOC, grid export/import, and more.

Set Battery Self-Use Mode

Configure battery charging/discharging thresholds:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_sn": "X3ABCD0123",
    "min_soc": 20,
    "charge_upper_soc": 80,
    "charge_from_grid_enable": 1
  }' \
  http://192.168.1.100:8000/api/battery/self-use-mode

Python / JavaScript Examples

Quick examples in Python and JavaScript are available in HTTP_API.md, including:

• Polling for real-time updates

• Time-based battery scheduling

• Error handling patterns

• Rate limiting considerations

Deployment on Raspberry Pi

Full deployment instructions (Docker installation, network setup, security, monitoring) are in DEPLOYMENT.md.

Docker Management

# View logs
docker-compose logs -f solax-http

# Restart the server
docker-compose restart solax-http

# Stop the server
docker-compose down

# Rebuild after code changes
docker-compose up -d --build

# Check resource usage
docker stats solax-http

Manual Testing

Quick Smoke Test

Before registering with Claude, you can test the client directly:

uv run --env-file .env python -c \
  "import asyncio; from solax_cloud_mcp.client import fetch_realtime_data; \
   from solax_cloud_mcp.config import get_default_device_sn; \
   print(asyncio.run(fetch_realtime_data(get_default_device_sn())))"

Run Tests

uv run pytest -v

Tests include:

• Response shaping and status decoding

• Environment variable validation

• Error handling and edge cases (battery-less devices, null status codes)

• Dynamic PV/MPPT parsing

• Case-insensitive field access

Interactive Inspection

If you have the MCP CLI tools installed:

uv run --env-file .env mcp dev src/solax_cloud_mcp/server.py

Rate Limiting

This server respects SolaX Developer Platform's documented rate limits:

• 100 calls per minute per token

• 1,000,000 calls per day per token

The client automatically enforces a 0.7-second minimum spacing between calls, which keeps typical usage well within both limits. No manual rate limiting is needed.

Data Fields Reference

All values are in SI units:

• Power: Watts (W)

• Energy: Kilowatt-hours (kWh)

• Voltage: Volts (V)

• Current: Amps (A)

• Temperature: Celsius (°C)

• Frequency: Hertz (Hz)

Inverter Status Codes

The inverter's status.code is an integer from the table below (Appendix 6 from the SolaX Developer Platform API docs). Not all possible codes are listed; consult the full Appendix 6 table on developer.solaxcloud.com/doc for the complete set.

Battery Status Codes (Residential)

The battery's battery.status.code is an integer:

API Error Codes (Appendix 1)

Troubleshooting

"SOLAX_CLIENT_ID environment variable not set"

• Set the SOLAX_CLIENT_ID environment variable or register the server with the correct credentials

"SOLAX_CLIENT_SECRET environment variable not set"

• Set the SOLAX_CLIENT_SECRET environment variable or register the server with the correct credentials

"No device_sn provided"

• Either pass the device_sn argument to the tool or set the SOLAX_DEVICE_SN environment variable

"SolaX API error 10402: Request access_token authentication failed"

• The server will automatically attempt to refresh the access token once; if this persists, your Client Secret may be invalid or revoked. Re-register your OAuth2 application at https://developer.solaxcloud.com/

"SolaX API error 10505: Device unauthorized"

• The device serial number you provided is invalid or not associated with your account. Double-check the device SN in your SolaX Developer Platform account.

"SolaX API error 10406: The API call rate has reached the upper limit"

• The rate limiter is correctly enforced; this should rarely occur under normal usage. If it does, the server automatically backs off. Reduce tool call frequency or wait a few seconds and retry.

"Network timeout"

• SolaX Developer Platform API is unreachable. Check your internet connection and confirm the service is online at https://developer.solaxcloud.com/.

Development

Project Structure

solax-cloud-mcp/
├── src/solax_cloud_mcp/
│   ├── __init__.py         # Package metadata
│   ├── __main__.py         # CLI entry point
│   ├── server.py           # MCP server and tool definitions
│   ├── client.py           # HTTP client and API calls
│   ├── auth.py             # OAuth2 token management
│   ├── config.py           # Environment variable handling
│   └── models.py           # Data models and response shaping
├── tests/
│   ├── fixtures/           # Test data
│   ├── test_config.py      # Configuration tests
│   └── test_models.py      # Response shaping tests
├── pyproject.toml          # Project metadata and dependencies
└── README.md               # This file

Adding Features

The server is designed to be minimal and focused. To add more endpoints/tools:

1. Fetch the data from SolaX Developer Platform API (extend client.py)

2. Add a response shaping function if needed (extend models.py)

3. Define a new @server.tool() in server.py

License

MIT

Support

For issues with this MCP server, open an issue on the repository.

For SolaX Developer Platform API documentation, refer to SolaX Developer Platform.