Alpha ESS

You can access Alpha ESS solar inverter and battery system data through a dedicated MCP server that exposes the official Alpha ESS Open API. This server lets you authenticate, retrieve system data, and configure battery behavior from your MCP client in a structured, reliable way.

How to use

Connect your MCP client to the Alpha ESS MCP server by starting the local MCP service and pointing your client to the server endpoint. You will authenticate with API credentials, then you can read energy statistics, real-time power data, and date-specific energy information. Use the available configuration and data retrieval functions to automate monitoring and control of your Alpha ESS systems.

How to install

uv sync

Create a configuration file named ".env" in the project root and add your Alpha ESS API credentials.

ALPHA_ESS_APP_ID=your_app_id_here
ALPHA_ESS_APP_SECRET=your_app_secret_here

To obtain your credentials, follow the steps to register as a developer and add your inverter system using the Serial Number (SN) and CheckCode, then generate AppID and AppSecret.

Optionally, you can run the server directly with the standard runtime command. Use the following example command to start the MCP server with the Python entry point.

uv run python /path/to/alpha-ess-mcp-server/main.py

Additional sections

Configuration details you may need to set up include the environment variables for API credentials and the exact command to run the server. You can place the credentials in a .env file or provide them in your MCP client configuration.

Example configuration for a Claude Desktop setup is shown here. Place this in your Claude Desktop config file. This config starts the MCP server as a stdio process and passes the credentials via environment variables.

{
  "mcpServers": {
    "alpha-ess": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/path/to/alpha-ess-mcp-server/main.py"
      ],
      "env": {
        "ALPHA_ESS_APP_ID": "your_app_id_here",
        "ALPHA_ESS_APP_SECRET": "your_app_secret_here"
      }
    }
  }
}

Testing the MCP server can be done by running the test suite specified for the project. Use the following command to exercise the available methods and ensure everything works as expected.

uv run python test_methods.py

Security and credentials

Keep your App ID and App Secret secure. Do not commit credentials to version control. Use environment variables or secret management in your deployment environment to protect these values.

Notes on data and capabilities

The server provides access to authentication and system management, data retrieval, and battery configuration functions. You can list registered Alpha ESS systems, fetch comprehensive energy statistics, get real-time power data, query specific dates for power and energy data, and view or set battery charging and discharging configurations.

Available tools

authenticate_alphaess

Validate API credentials against the Alpha ESS Open API to ensure your App ID and App Secret are correct.

get_ess_list

Retrieve a list of all Alpha ESS inverter/battery systems registered to your account.

get_alpha_ess_data

Fetch comprehensive energy statistics for all registered Alpha ESS systems.

get_last_power_data

Obtain a real-time snapshot of current power data for a specific system (optionally by serial).

get_one_day_power_data

Get detailed power data for a specific date for one or more systems.

get_one_date_energy_data

Retrieve energy totals for a specific date across your Alpha ESS systems.

get_charge_config

Query the current battery charging configuration for a system.

get_discharge_config

Query the current battery discharging configuration for a system.

set_battery_charge

Configure battery charging windows and behavior for a system.

set_battery_discharge

Configure battery discharging windows and behavior for a system.