Alpha ESS MCP Server
A Model Context Protocol (MCP) server that provides access to Alpha ESS solar inverter and battery system data through the official Alpha ESS Open API.
Installation
uv sync
Configuration
Create a .env file in the project root:
ALPHA_ESS_APP_ID=your_app_id_here
ALPHA_ESS_APP_SECRET=your_app_secret_here
To get your Alpha ESS API credentials:
- Visit https://open.alphaess.com/
- Create a developer account
- Add your inverter system using the Serial Number (SN) and CheckCode
- Obtain your AppID and AppSecret
Usage with Claude Desktop
Add to your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"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"
}
}
}
}
Available Tools
Authentication & System Management
authenticate_alphaess()- Validate API credentialsget_ess_list()- List all registered Alpha ESS systems
Data Retrieval
get_alpha_ess_data()- Get comprehensive energy statistics for all systemsget_last_power_data(serial?)- Get real-time power data snapshotget_one_day_power_data(query_date, serial?)- Get detailed power data for a specific dateget_one_date_energy_data(query_date, serial?)- Get energy summary for a specific date
Battery Configuration
get_charge_config(serial?)- Get current battery charging configurationget_discharge_config(serial?)- Get current battery discharge configurationset_battery_charge(enabled, dp1_start, dp1_end, dp2_start, dp2_end, charge_cutoff_soc, serial?)- Configure battery charging scheduleset_battery_discharge(enabled, dp1_start, dp1_end, dp2_start, dp2_end, discharge_cutoff_soc, serial?)- Configure battery discharge schedule
Parameters
serial(optional) - System serial number. If not provided, automatically selects the first system if only one existsquery_date- Date in YYYY-MM-DD formatenabled- Boolean to enable/disable the configurationdp1_start/dp1_end, dp2_start/dp2_end- Time periods in HH:MM format (minutes must be :00, :15, :30, :45)charge_cutoff_soc/discharge_cutoff_soc- SOC percentage (0-100)
Testing
uv run python test_methods.py
License
MIT License