Servidor MCP de Enphase Solar

Un servidor MCP que conecta Claude Desktop a la API v4 de desarrolladores de Enphase oficial. De solo lectura por defecto; las escrituras para batería y cargador de VE están disponibles mediante una opción de activación. Sin extracción de contraseñas: acceso OAuth 2.0 limpio a los datos de tu propio sistema.

Qué obtienes

30 herramientas de lectura (siempre activas), agrupadas por propósito:

3 herramientas de escritura (activación mediante ENPHASE_ENABLE_WRITES=1):

Estas acciones cambian el comportamiento del equipo físico sin posibilidad de deshacer. Mantenlas desactivadas a menos que desees específicamente un control de tu hardware mediante IA.

Advertencias sobre el plan y el hardware

• Plan de suscripción. El plan gratuito Watt cubre los detalles del sistema + producción/consumo a nivel de sitio, suficiente para la mayoría de las herramientas de lectura. La telemetría por dispositivo, la protección contra tormentas (Storm Guard) y algunos endpoints de batería pueden requerir el plan Kilowatt o superior. Un error 401 en una herramienta específica generalmente significa "actualiza tu plan".

• Hardware requerido. Las herramientas de batería necesitan una batería Enphase IQ / Encharge. Las herramientas de cargador de VE necesitan un cargador Enphase IQ (los conectores de pared de Tesla y cargadores de terceros son invisibles para Enphase). Un error 404 en una de estas herramientas generalmente significa "no tienes ese dispositivo".

• Los errores de la API se propagan tal cual para que puedas identificar qué caso estás encontrando.

Requisitos previos

• Python 3.11+

• Una cuenta de Enphase Enlighten con tu sistema

• Una cuenta de desarrollador de Enphase en https://developer-v4.enphase.com (el plan gratuito Watt es suficiente: 1.000 llamadas/mes)

Configuración

1. Registrar una aplicación de desarrollador

1. Regístrate en https://developer-v4.enphase.com

2. Suscríbete al plan Watt (gratuito)

3. Crea una nueva aplicación

4. Establece el URI de redirección en https://api.enphaseenergy.com/oauth/redirect_uri (por defecto)

5. Anota tu API Key, Client ID y Client Secret

2. Encuentra tu ID de sistema

Inicia sesión en https://enlighten.enphaseenergy.com: tu ID de sistema está en la URL: https://enlighten.enphaseenergy.com/web/{SYSTEM_ID}/today

(Si aún no lo conoces, déjalo en blanco en .env y usa get_systems una vez que el servidor esté en marcha para descubrirlo).

3. Instalación

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

4. Configurar credenciales

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. Ejecutar el flujo de autenticación único

python auth_setup.py

El script imprime una URL de autorización. Asegúrate de haber iniciado sesión en Enlighten en el mismo navegador, luego abre la URL y aprueba el acceso para tu sistema. Serás redirigido a una página que muestra tu código de autorización. Cópialo y pégalo en la terminal.

Esto crea tokens.json con tus tokens de acceso y actualización. A partir de ahí, el cliente se actualiza automáticamente en cada llamada a la API.

6. Conectar a Claude Desktop

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

Reinicia Claude Desktop por completo (⌘Q en macOS, no solo cerrar la ventana). Deberías ver un indicador de herramientas en la entrada del chat. Pregunta cosas como "¿cuánto produjimos hoy frente a ayer?" o "¿cuál fue nuestro día de mayor producción este mes?".

Comportamiento de actualización de tokens

• Los tokens de acceso duran 1 hora

• Los tokens de actualización duran ~1 semana de inactividad; cualquier llamada a la API reinicia el temporizador

• Si la actualización falla, vuelve a ejecutar python auth_setup.py

Opcional: mantenimiento automático (keepalive)

Si no consultas Enphase semanalmente, puedes ejecutar keepalive.py según un programa para mantener vivo el token de actualización. Llama a /systems una vez y registra en keepalive.log. En macOS, coloca un LaunchAgent en ~/Library/LaunchAgents/com.enphase-mcp.keepalive.plist apuntando al Python del venv y a keepalive.py, con StartInterval establecido en 259200 (3 días); eso da ~4 días de margen dentro de la ventana de inactividad de 7 días. Cárgalo con launchctl bootstrap gui/$(id -u) <plist>.

Añadir más endpoints

La superficie de la API v4 de Enphase está documentada en https://developer-v4.enphase.com/docs y la especificación Swagger completa está en https://developer-v4.enphase.com/swagger/spec/System_API.json (47 endpoints; este servidor envuelve la mayoría de ellos, pero omite la telemetría por microinversor, los endpoints de bombas de calor, la búsqueda multisistema y algunos endpoints especializados de lectura de medidores).

Para añadir uno, coloca un nuevo método en server.py siguiendo el patrón existente:

@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})

Solución de problemas

401 en ciertos endpoints: Problema de nivel de plan. La mayoría de las lecturas funcionan en Watt; algunas requieren Kilowatt+.

404 en endpoints de batería / cargador de VE: No tienes ese hardware en tu sistema.

406 en la URL de autenticación: No has iniciado sesión en Enlighten en el navegador. Inicia sesión primero y luego vuelve a abrir la URL de autenticación.

"No tokens found": Ejecuta python auth_setup.py.

Claude no ve las herramientas: Revisa los registros de Claude Desktop en ~/Library/Logs/Claude/ (macOS) o %APPDATA%\Claude\logs\ (Windows). La mayoría de los problemas son problemas de rutas absolutas en claude_desktop_config.json.