solarnetwork-mcp

Un servidor MCP que convierte la telemetría solar de SolarNetwork en herramientas que un agente de IA puede llamar.

No requiere credenciales. Se ejecuta contra los endpoints públicos de SolarNetwork, donde ~52 sitios solares en vivo publican datos reales de generación, irradiancia y clima; varios de ellos se actualizan al minuto, con seis años de historial.

Lo que puede hacer

Leer telemetría solar

• Descubrir nodos públicos sin credenciales, filtrar por zona horaria o actividad

• Clasificar cada flujo de un sitio: medidor del sitio, inversor, irradiancia, clima, anomalía de ML

• Consultar series temporales en cualquier agregación de cinco minutos a un año

• Obtener la energía acumulada real a partir de las lecturas del medidor, no la potencia promediada

• Comprobar si un flujo sigue activo, por marca de tiempo en lugar de por valor

Detectar fallos de equipos, con fechas

• Detectar cortes de inversor y fijar el día exacto de inicio y fin

• Distinguir un dispositivo muerto de uno que está generando pero no notifica potencia

• Detectar un dispositivo que ha quedado en silencio mientras sus hermanos siguen notificando

• Marcar reinicios del contador del medidor, que corrompen silenciosamente todos los totales de energía que los abarcan

• Detectar entradas del registro correspondientes a hardware que nunca ha existido

• Estimar la energía perdida por fallo, escalada desde la producción de los hermanos según la capacidad de cada dispositivo

No generar falsas alarmas

• La detección es relativa a los pares, por lo que la nubosidad no puede registrarse como fallo

• La irradiancia se usa como control físico del clima cuando existe un piranómetro

• Los fallos ya activos cuando se abre la ventana se etiquetan como cotas inferiores, no como fechas de inicio inventadas

• Los sitios que no pueden evaluarse se notifican como no evaluados, nunca como saludables

Escribir informes que la gente pueda usar

• Órdenes de trabajo priorizadas con causa en lenguaje sencillo, evidencia, pasos numerados, herramientas y criterios de aprobación

• Paquetes de campo PDF imprimibles con casillas de verificación y una hoja de notas

• Markdown para pegar en un ticket, o JSON para posprocesar

• ASCII simple en todo, para que nada se convierta en cuadros negros en un PDF o un sistema de tickets

Lo que no puede hacer

Vale la pena saberlo antes de confiar en él:

• Los sitios con menos de dos inversores no pueden evaluarse. La comparación entre pares necesita pares. La herramienta lo dice en lugar de informar de un resultado limpio.

• Sin potencia de placa. Los nodos públicos no la exponen, así que las cifras de pérdida son estimaciones escaladas entre pares, no cálculos de garantía.

• La detección de fallos se ejecuta en intervalos diarios. Un dispositivo en silencio durante seis horas es invisible.

• La clasificación de flujos depende de una convención de rutas. Los sitios que nombran los flujos Main o SMAInverter1 vuelven sin clasificar.

Lo que hace realmente

Sin él, responder "¿hay algo mal en este sitio?" significa conocer el ID del nodo, el endpoint /datum/list, que existe aggregation=Day, que watts y wattHours son preguntas distintas, y luego leer JSON.

Con él, preguntas:

"¿Hay algo mal en el nodo 1000? Si la producción ha caído, dime si es clima o equipo."

y el agente descubre los flujos del sitio, elige un rango de fechas, ejecuta la agregación, compara cada inversor con sus hermanos y responde en inglés. Una frase entra, un diagnóstico sale.

El servidor se encarga de las partes en las que un modelo de lenguaje es malo — firma de solicitudes, paginación, semántica de unidades, saber cuál de nueve flujos es un sensor meteorológico. El agente se encarga de las partes en las que es bueno — decidir qué preguntar e interpretar la respuesta.

Míralo funcionar en 60 segundos

npm install && npm run build && npm run smoke

Eso ejecuta todas las herramientas a través del protocolo MCP real contra datos en vivo. Sin agente, sin clave de API, sin configuración. Si imprime hallazgos para el nodo 1000, estás listo.

Entrégaselo a tu agente

Copia todo el bloque siguiente en Claude Code, Cursor o cualquier agente compatible con MCP. Instala el servidor, se configura solo, comprueba que la instalación funciona y luego ejecuta una demostración guiada de cada capacidad contra sitios solares públicos en vivo.

Set up and demo the solarnetwork MCP server for me.

1. INSTALL
   git clone https://github.com/gopisrikrishna/solarnetwork-mcp.git
   cd solarnetwork-mcp
   npm install
   npm run build

2. VERIFY THE INSTALL
   Run: npm run verify
   This runs 28 assertions against live public solar data. No credentials needed.
   Tell me how many passed. If any fail, show me which and stop.

3. CONNECT IT
   Register the server with yourself over stdio:
     command: node
     args:    ./dist/index.js   (run from the solarnetwork-mcp directory)
   The repo ships a .mcp.json that already does this. Restart/reconnect if your
   client needs it, then confirm you can see 10 tools and list their names.

4. DEMO IT
   Work through these against real public nodes and show me what you find.
   Explain your reasoning at each step, do not just dump JSON.

   a) DISCOVERY
      Which public nodes are live in US timezones? Then: what does node 1000
      measure, and how far back does its data go?

   b) ENERGY
      How much did node 1000 generate in July 2026? Use the right tool for a
      billing-shaped question and tell me why you chose it.

   c) FAULT DETECTION  <- the interesting one
      Run an asset review on node 1000 for 2026-01-01 to 2026-09-01.
      Tell me what broke, exactly when it started and ended, and what it cost.
      There is a real 79-day inverter outage in there, and a second fault where
      a device reports 0 watts while still generating. Explain the difference
      between those two failure modes and why it matters.

   d) NOT BEING FOOLED
      Run an asset review on node 949 for July 2026. It will find nothing.
      Explain why "no faults found" does NOT mean the site is healthy here.

   e) DATA INTEGRITY
      Run an asset review on node 781 for 2026-01-01 to 2026-09-01.
      Its site meter counter reset mid-year. Show me how the tool handles it and
      what would have gone wrong without that handling.

   f) CROSS-CHECK
      Node 392 publishes the platform's own ML anomaly streams. Compare what
      get_anomalies says against what the asset review found. Do they agree?

   g) REPORT
      Generate a PDF service report for node 1000 over the same window, written
      for an on-site technician. Save it and tell me the path, how many pages,
      and summarise the priority 1 jobs.

5. WRAP UP
   Tell me in plain language: what is wrong with node 1000, how much energy has
   been lost, and what you would send a technician to do first.

Verifícalo tú mismo

Como se ejecuta sobre datos públicos, no tienes que aceptar ninguna de sus conclusiones sin más. Cada hallazgo es reproducible de forma independiente desde tu propia máquina:

npm install && npm run build && npm run verify

28 aserciones contra ventanas históricas fijas en nodos públicos en vivo. Sin credenciales. Entre ellas:

Un fallo significa que el servidor ha sufrido una regresión, o que SolarNetwork ha reformulado el historial. Cada aserción imprime lo que esperaba frente a lo que obtuvo, de modo que ambos son fáciles de distinguir.

Cárgalo en tu agente

Todo cliente necesita los mismos tres datos: ejecutar node, pasarle dist/index.js, hablar por stdio. Solo difiere la ubicación del archivo.

Usa la ruta absoluta a dist/index.js en tu máquina. Las barras diagonales también funcionan en Windows.

El .mcp.json incluido aquí usa en su lugar una ruta relativa, para que cualquiera que clone el repositorio obtenga un servidor funcional sin editar nada. Eso solo funciona con clientes que lanzan el servidor desde la raíz del proyecto, como hace Claude Code; otros clientes pueden necesitar la forma absoluta.

Claude Code

Ya configurado — .mcp.json está en la raíz del repositorio, así que una sesión iniciada en este directorio lo recoge automáticamente. Solo edita la ruta:

{
  "mcpServers": {
    "solarnetwork": {
      "command": "node",
      "args": ["/absolute/path/to/solarnetwork-mcp/dist/index.js"]
    }
  }
}

O regístralo globalmente desde cualquier lugar:

claude mcp add solarnetwork -- node /absolute/path/to/solarnetwork-mcp/dist/index.js

Claude Desktop

Edita claude_desktop_config.json:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "solarnetwork": {
      "command": "node",
      "args": ["/absolute/path/to/solarnetwork-mcp/dist/index.js"]
    }
  }
}

Reinicia la aplicación. Aparece un icono de herramientas en el cuadro de mensaje.

Cursor

.cursor/mcp.json en tu proyecto, o ~/.cursor/mcp.json para todos los proyectos. El mismo bloque mcpServers de arriba.

Windsurf

~/.codeium/windsurf/mcp_config.json. El mismo bloque mcpServers.

VS Code (modo agente de Copilot)

.vscode/mcp.json — nota que la clave es servers, no mcpServers:

{
  "servers": {
    "solarnetwork": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/solarnetwork-mcp/dist/index.js"]
    }
  }
}

Zed

En settings.json, bajo context_servers:

{
  "context_servers": {
    "solarnetwork": {
      "command": { "path": "node", "args": ["/absolute/path/to/dist/index.js"] }
    }
  }
}

Cualquier otro

Cualquier cliente MCP puede lanzarlo a través de stdio:

node /absolute/path/to/solarnetwork-mcp/dist/index.js

Para manejarlo desde código, scripts/smoke.mjs es un ejemplo completo y funcional que usa el SDK oficial de TypeScript.

Comprobar que se ha cargado

Pregunta a tu agente: "¿Qué herramientas solares tienes?" Deberías ver diez. Si no, las causas habituales son una ruta relativa, un npm run build no ejecutado, o que el cliente no se haya reiniciado.

Las herramientas

Descubrimiento

Datos

Análisis

Informes

Cosas que puedes preguntarle

Empieza aquí: estos son nodos reales y en vivo:

Orientación

¿Qué nodos públicos de SolarNetwork están en vivo en zonas horarias de EE. UU.?

¿Qué mide el nodo 1000 y hasta cuándo se remontan sus datos?

Ahora mismo

¿Qué está generando el nodo 892 ahora mismo y qué tiempo hace allí?

El nodo 892 lleva un sensor meteorológico y un piranómetro, así que el agente obtiene temperatura, nubosidad e irradiancia junto con la producción.

Diagnóstico — los interesantes

¿Hay algo mal en el nodo 1000?

El nodo 892 enumera seis inversores pero no veo generación. ¿Qué está pasando?

Flota

Ordena los nodos 880, 884, 953, 964, 976, 987 y 1000 por producción de la semana pasada. ¿A cuál debería mirar primero?

Multi-paso, donde el encadenamiento se nota

Encuentra un nodo estadounidense en vivo con al menos cuatro inversores y datos de irradiancia, y luego diagnostícalo durante las últimas dos semanas.

Lo que obtienes como respuesta

Salida real de diagnose_site en el nodo 1000:

[high] reporting-gap   /0145/S1/G1/GEN/101, /102, /103
       Registered on this node but returned no data for the window. That is a
       reporting or comms outage rather than a performance problem, so the
       device may well be generating.

[low]  inconsistent-instrumentation   /0145/S1/G1/INV/4
       Reports 0 W, but its `wh` field is non-zero (peak 16508), so it is moving
       energy. This device populates energy fields only, unlike its peers, so
       power-based comparison would wrongly read it as dead.

Ese segundo hallazgo es el sentido de todo el proyecto. INV/4 marca 0 W mientras sus tres hermanos producen 400–700 W, lo que parece exactamente un inversor muerto — y una versión anterior de esta herramienta lo decía. No está muerto: su medidor acumuló 826 kWh ese mes. Los inversores de un mismo sitio usan convenciones de notificación diferentes. Una comprobación de salud basada solo en watts avisaría a alguien cada noche por un inversor que funciona.

Tus propios nodos

Establece dos variables de entorno y el servidor cambia de los endpoints públicos /pub a los autenticados /sec. La superficie de herramientas no cambia:

SN_TOKEN_ID=... SN_TOKEN_SECRET=... node dist/index.js

La autenticación es el esquema SNWS2 de SolarNetwork — HMAC-SHA256 sobre una solicitud canonicalizada con una clave con ámbito de fecha. Está implementada pero sin probar; no tengo un par de tokens contra el que verificar.

Cómo funciona

Tres archivos, ~900 líneas en total:

• src/solarnetwork.ts — cliente de API, paginación, firma de solicitudes

• src/analysis.ts — análisis de ID de fuente, diagnóstico por sitio

• src/index.ts — las diez definiciones de herramientas

Las descripciones de las herramientas son la interfaz real. Un agente solo encadena correctamente list_sources → query_datum si las descripciones dicen cuándo recurrir a cada una. Lograr esa redacción importó más para que esto funcione que cualquier manejo de datos.

Limitaciones

• Los metadatos de los nodos están vacíos en los nodos públicos, así que no hay capacidad de placa y, por tanto, ninguna comparación normalizada por capacidad. compare_fleet ordena por producción bruta y lo dice: un sitio grande superará a uno pequeño y sano.

• list_public_nodes lee un escaneo puntual (data/nodes.json), no un listado en vivo. Llama a list_sources para confirmar antes de confiar en un nodo.

• Sin caché. Las llamadas repetidas del agente vuelven a llamar a la API.

• Sin pruebas unitarias. scripts/smoke.mjs es una sonda en vivo, no una suite de pruebas.

• SolarQuery convierte silenciosamente la agregación de grano fino a horaria para rangos de más de ~7 días. query_datum pasa tu agregación tal cual, así que los rangos largos devuelven datos de menor resolución de lo solicitado.

Más detalle: USAGE.md para ejemplos prácticos y una comparación de esfuerzo, DATA.md para el inventario completo de lo que es público frente a lo que requiere credenciales.

Licencia

MIT