Enphase Solar MCP 서버

Claude Desktop을 공식 Enphase Developer API v4에 연결하는 MCP 서버입니다. 기본적으로 읽기 전용이며, 배터리 및 EV 충전기 쓰기 기능은 옵트인(opt-in) 플래그를 통해 사용할 수 있습니다. 비밀번호 스크래핑 없이 OAuth 2.0을 통해 자신의 시스템 데이터에 안전하게 액세스합니다.

제공 기능

30개의 읽기 도구(항상 켜짐), 목적별 그룹화:

3개의 쓰기 도구 (ENPHASE_ENABLE_WRITES=1을 통해 옵트인):

이 도구들은 물리적 장비의 동작을 되돌릴 수 없게 변경합니다. 하드웨어를 LLM으로 제어하려는 특별한 목적이 없다면 비활성화 상태로 두십시오.

플랜 및 하드웨어 주의사항

• 구독 플랜. 무료 Watt 플랜은 시스템 세부 정보 및 사이트 수준의 발전/소비 데이터를 포함하며, 대부분의 읽기 도구를 사용하기에 충분합니다. 장치별 원격 측정, 스톰 가드 및 일부 배터리 엔드포인트는 Kilowatt 이상의 플랜이 필요할 수 있습니다. 특정 도구에서 401 오류가 발생하면 일반적으로 "플랜 업그레이드"가 필요함을 의미합니다.

• 필수 하드웨어. 배터리 도구는 Enphase IQ Battery / Encharge가 필요합니다. EV 충전기 도구는 Enphase IQ EV 충전기가 필요합니다(Tesla Wall Connector 및 타사 충전기는 Enphase에서 인식되지 않습니다). 이 도구들에서 404 오류가 발생하면 일반적으로 "해당 장치가 없음"을 의미합니다.

• API 오류는 그대로 전달되므로 어떤 상황인지 확인할 수 있습니다.

사전 요구 사항

• Python 3.11+

• 시스템이 등록된 Enphase Enlighten 계정

• https://developer-v4.enphase.com 의 Enphase 개발자 계정 (무료 Watt 플랜으로 충분함 — 월 1,000회 호출)

설정

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 에 로그인하면 URL에서 시스템 ID를 확인할 수 있습니다: 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. 1회성 인증 흐름 실행

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를 다시 실행하십시오.

선택 사항: 자동 유지(keepalive)

매주 Enphase를 조회하지 않는 경우, 일정에 따라 keepalive.py를 실행하여 새로 고침 토큰을 유지할 수 있습니다. 이 스크립트는 /systems를 한 번 호출하고 keepalive.log에 기록합니다. macOS의 경우 ~/Library/LaunchAgents/com.enphase-mcp.keepalive.plist에 LaunchAgent를 배치하고 venv의 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 이상이 필요합니다.

배터리 / EV 충전기 엔드포인트에서 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의 절대 경로 문제입니다.