Enphase Solar MCP 服务器

一个将 Claude Desktop 连接到官方 Enphase Developer API v4 的 MCP 服务器。默认只读；电池和电动汽车充电器写入功能可通过选择性标志启用。无需抓取密码 — 通过 OAuth 2.0 安全访问您自己的系统数据。

您将获得什么

30 个只读工具（始终开启），按用途分组：

分组	工具
概览	`get_systems`, `get_system_summary`, `get_latest_telemetry`, `get_live_data`, `get_devices`
累计总量	`get_lifetime_production`, `get_lifetime_consumption`, `get_lifetime_battery`, `get_lifetime_grid_import`, `get_lifetime_grid_export`
遥测（间隔）	`get_production_telemetry`, `get_consumption_telemetry`, `get_battery_telemetry`, `get_grid_import_telemetry`, `get_grid_export_telemetry`
事件 / 健康状况	`get_events`, `get_open_events`, `get_alarms`, `get_open_alarms`, `get_event_types`
只读配置	`get_battery_settings`, `get_storm_guard_settings`, `get_grid_status`, `get_load_control_settings`
电动汽车充电器	`get_ev_charger_devices`, `get_ev_charger_events`, `get_ev_charger_lifetime`, `get_ev_charger_telemetry`, `get_ev_charger_sessions`, `get_ev_charger_schedules`

3 个写入工具（通过 ENPHASE_ENABLE_WRITES=1 选择性启用）：

工具	修改内容
`update_battery_settings`	修改电池模式/储备/计划
`start_ev_charging`	启动 Enphase IQ 电动汽车充电器
`stop_ev_charging`	停止 Enphase IQ 电动汽车充电器

这些操作会改变物理设备的行为且无法撤销。除非您明确需要 LLM 控制您的硬件，否则请保持关闭。

计划和硬件注意事项

订阅计划。 免费的 Watt 计划涵盖系统详情 + 站点级发电/用电数据 — 足以支持大多数只读工具。设备级遥测、风暴防护和某些电池端点可能需要 Kilowatt 或更高级别。特定工具返回 401 通常意味着“请升级您的计划”。
硬件要求。 电池工具需要 Enphase IQ Battery / Encharge。电动汽车充电器工具需要 Enphase IQ 电动汽车充电器（Tesla Wall Connectors 和第三方充电器对 Enphase 不可见）。这些工具返回 404 通常意味着“您没有该设备”。
API 错误会按原样传播，以便您判断遇到了哪种情况。

先决条件

Python 3.11+
拥有系统的 Enphase Enlighten 账户
在 https://developer-v4.enphase.com 注册的 Enphase 开发者账户（免费的 Watt 计划即可 — 每月 1,000 次调用）

设置

1. 注册开发者应用

在 https://developer-v4.enphase.com 注册
订阅 Watt 计划（免费）
创建一个新应用
将 Redirect URI 设置为 https://api.enphaseenergy.com/oauth/redirect_uri（默认）
记下您的 API Key、Client ID 和 Client Secret

2. 查找您的系统 ID

（如果您还不知道，请在 .env 中留空，并在服务器运行后使用 get_systems 进行查找。）

3. 安装

cd enphase-mcp
python3 -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt

4. 配置凭据

cp .env.example .env
# Edit .env and fill in API key, client ID, client secret, system ID
# (Optional) uncomment ENPHASE_ENABLE_WRITES=1 to expose write tools.

5. 运行一次性授权流程

python auth_setup.py

脚本会打印一个授权 URL。确保您已在同一浏览器中登录 Enlighten，然后打开该 URL，批准对您系统的访问。您将被重定向到一个显示授权码的页面。复制并粘贴到终端中。

这将创建一个包含您的访问令牌和刷新令牌的 tokens.json 文件。此后，客户端会在每次 API 调用时自动刷新令牌。

6. 连接到 Claude Desktop

编辑 claude_desktop_config.json：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "enphase": {
      "command": "/absolute/path/to/enphase-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/enphase-mcp/server.py"]
    }
  }
}

完全重启 Claude Desktop（macOS 上使用 ⌘Q，不要只关闭窗口）。您应该会在聊天输入框中看到工具指示器。尝试询问诸如 “我们今天比昨天发电量如何？” 或 “本月我们的最高发电量是哪一天？” 之类的问题。

令牌刷新行为

访问令牌有效期为 1 小时
刷新令牌在约 1 周不活动后失效 — 任何 API 调用都会重置计时器
如果刷新失败，请重新运行 python auth_setup.py

可选：自动保持活跃

如果您每周不查询 Enphase，可以按计划运行 keepalive.py 以保持刷新令牌活跃。它会调用一次 /systems 并记录到 keepalive.log。在 macOS 上，可以在 ~/Library/LaunchAgents/com.enphase-mcp.keepalive.plist 放置一个 LaunchAgent，指向虚拟环境的 Python 和 keepalive.py，并将 StartInterval 设置为 259200（3 天）— 这在 7 天的不活动窗口内提供了约 4 天的缓冲。使用 launchctl bootstrap gui/$(id -u) <plist> 加载它。

添加更多端点

Enphase v4 API 接口文档位于 https://developer-v4.enphase.com/docs，完整的 Swagger 规范位于 https://developer-v4.enphase.com/swagger/spec/System_API.json（共有 47 个端点；此服务器封装了其中大部分，但跳过了微型逆变器遥测、热泵端点、多系统搜索以及一些专门的电表读取端点）。

要添加一个端点，请按照现有模式将新方法放入 server.py：

@mcp.tool()
def my_new_tool(some_param: str) -> dict:
    """What this returns."""
    sid = client.require_system_id()
    return client.get(f"/systems/{sid}/some_endpoint", params={"x": some_param})

故障排除

特定端点返回 401： 计划等级问题。大多数读取操作在 Watt 计划下有效；部分需要 Kilowatt+。

电池/电动汽车充电器端点返回 404： 您的系统中没有该硬件。

授权 URL 返回 406： 您未在浏览器中登录 Enlighten。请先登录，然后重新打开授权 URL。

“No tokens found”： 运行 python auth_setup.py。

Claude 看不到工具： 检查 ~/Library/Logs/Claude/ (macOS) 或 %APPDATA%\Claude\logs\ (Windows) 下的 Claude Desktop 日志。大多数问题都是 claude_desktop_config.json 中的绝对路径问题。

Enphase Solar MCP Server