Alpha Ess Solar Energy System Server

Alpha ESS MCP 服务

一个模型上下文协议（MCP）服务，可通过 Alpha ESS 官方 Open API 访问 Alpha ESS 太阳能逆变器和电池系统数据。

安装

uv sync

配置

在项目根目录创建一个 .env 文件：

ALPHA_ESS_APP_ID=your_app_id_here
ALPHA_ESS_APP_SECRET=your_app_secret_here

获取 Alpha ESS API 凭据的步骤：

1. 访问 https://open.alphaess.com/
2. 创建开发者账户
3. 使用序列号（SN）和 CheckCode 添加逆变器系统
4. 获取 AppID 和 AppSecret

在 Claude Desktop 中使用

添加到 Claude Desktop 配置文件：

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

可用工具

身份验证与系统管理

• authenticate_alphaess() - 验证 API 凭据
• get_ess_list() - 列出所有已注册的 Alpha ESS 系统

数据检索

• get_alpha_ess_data() - 获取所有系统的综合能源统计数据
• get_last_power_data(serial?) - 获取实时功率数据快照
• get_one_day_power_data(query_date, serial?) - 获取指定日期的详细功率数据
• get_one_date_energy_data(query_date, serial?) - 获取指定日期的能源摘要

电池配置

• get_charge_config(serial?) - 获取当前电池充电配置
• get_discharge_config(serial?) - 获取当前电池放电配置
• set_battery_charge(enabled, dp1_start, dp1_end, dp2_start, dp2_end, charge_cutoff_soc, serial?) - 配置电池充电计划
• set_battery_discharge(enabled, dp1_start, dp1_end, dp2_start, dp2_end, discharge_cutoff_soc, serial?) - 配置电池放电计划

参数

• serial（可选）- 系统序列号。如果未提供，且仅有一个系统，则自动选择该系统
• query_date - 日期，格式为 YYYY-MM-DD
• enabled - 用于启用/停用配置的布尔值
• dp1_start/dp1_end, dp2_start/dp2_end - 时间段，格式为 HH:MM（分钟必须为 :00、:15、:30 或 :45）
• charge_cutoff_soc/discharge_cutoff_soc - SOC 百分比（0-100）

测试

uv run python test_methods.py

许可证

MIT 许可证

参考资料

• Alpha ESS Open API 文档
• alphaess-openAPI 库
• 模型上下文协议