Enphase Solar MCP Server

MCP-сервер, подключающий Claude Desktop к официальному Enphase Developer API v4. По умолчанию работает в режиме только чтения; запись для аккумуляторов и зарядных устройств для электромобилей доступна при включении соответствующего флага. Никакого сбора паролей — чистый доступ через OAuth 2.0 к данным вашей собственной системы.

Что вы получаете

30 инструментов для чтения (всегда включены), сгруппированных по назначению:

3 инструмента для записи (включаются через ENPHASE_ENABLE_WRITES=1):

Эти инструменты изменяют поведение физического оборудования без возможности отмены. Оставляйте их выключенными, если вам не требуется управление оборудованием с помощью LLM.

Ограничения плана и оборудования

• План подписки. Бесплатный план Watt покрывает детали системы + производство/потребление на уровне объекта — этого достаточно для большинства инструментов чтения. Телеметрия по отдельным устройствам, защита от шторма (storm guard) и некоторые конечные точки аккумуляторов могут требовать план Kilowatt или выше. Ошибка 401 при использовании конкретного инструмента обычно означает «обновите ваш план».

• Необходимое оборудование. Инструменты для аккумуляторов требуют наличия Enphase IQ Battery / Encharge. Инструменты для зарядных устройств для ЭМ требуют наличия Enphase IQ EV charger (Tesla Wall Connectors и сторонние зарядные устройства не видны для Enphase). Ошибка 404 от одного из них обычно означает «у вас нет этого устройства».

• Ошибки API передаются как есть, чтобы вы могли понять, с какой ситуацией столкнулись.

Предварительные требования

• Python 3.11+

• Учетная запись Enphase Enlighten с вашей системой

• Учетная запись разработчика Enphase на https://developer-v4.enphase.com (бесплатного плана Watt достаточно — 1000 вызовов в месяц)

Настройка

1. Регистрация приложения разработчика

1. Зарегистрируйтесь на https://developer-v4.enphase.com

2. Подпишитесь на план Watt (бесплатно)

3. Создайте новое приложение

4. Установите Redirect URI на https://api.enphaseenergy.com/oauth/redirect_uri (по умолчанию)

5. Запишите ваши API Key, Client ID и Client Secret

2. Поиск ID вашей системы

Войдите на https://enlighten.enphaseenergy.com — ID вашей системы находится в URL: https://enlighten.enphaseenergy.com/web/{SYSTEM_ID}/today

(Если вы его еще не знаете, оставьте поле пустым в .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 (⌘Q на macOS, а не просто закрытие окна). Вы должны увидеть индикатор инструментов в поле ввода чата. Задавайте вопросы вроде «сколько мы произвели сегодня по сравнению со вчерашним днем?» или «каким был пик производства в этом месяце?».

Поведение при обновлении токенов

• Токены доступа действуют 1 час

• Токены обновления действуют около 1 недели бездействия — любой вызов API сбрасывает таймер

• Если обновление не удалось, снова запустите python auth_setup.py

Дополнительно: автоматическое поддержание активности

Если вы не делаете запросы к Enphase еженедельно, вы можете запускать keepalive.py по расписанию, чтобы поддерживать токен обновления в активном состоянии. Он вызывает /systems один раз и записывает результат в keepalive.log. На macOS добавьте LaunchAgent в ~/Library/LaunchAgents/com.enphase-mcp.keepalive.plist, указывающий на Python из виртуального окружения и keepalive.py, с параметром StartInterval, установленным на 259200 (3 дня) — это дает около 4 дней запаса внутри 7-дневного окна неактивности. Загрузите его с помощью 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 на конечных точках аккумулятора / зарядного устройства для ЭМ: У вас нет этого оборудования в системе.

406 на URL авторизации: Вы не вошли в Enlighten в браузере. Сначала войдите, затем снова откройте URL авторизации.

"No tokens found": Запустите python auth_setup.py.

Claude не видит инструменты: Проверьте логи Claude Desktop в ~/Library/Logs/Claude/ (macOS) или %APPDATA%\Claude\logs\ (Windows). Большинство проблем связано с неправильными абсолютными путями в claude_desktop_config.json.