APsystems MCP Server

APsystems MCP Server ☀️🛰️

Un servidor de Model Context Protocol (MCP) listo para producción escrito en Go que envuelve la APsystems OpenAPI, brindando a asistentes de IA como Claude acceso directo a tus datos de monitoreo solar. Incluye un panel web opcional para monitoreo visual.

Tabla de contenido

• APsystems MCP Server ☀️🛰️
  • Tabla de contenido
  • Características
  • Inicio rápido
    • 🚀 Requisitos previos
    • Instalación & ejecución
    • Con transporte SSE
    • Con panel web
  • Demo del panel web
    • iniciar con Podman
  • Tabla de variables de entorno
  • Seguridad
  • Referencia de herramientas MCP
    • Herramientas del sistema
    • Herramientas ECU
    • Herramientas de inversores
    • Herramientas de medidores
    • Herramientas de almacenamiento
  • Uso con Claude Desktop
  • Uso con Claude CLI
    • 1. Iniciar el servidor MCP
    • 2. Configurar Claude CLI
    • 3. Ejemplo de uso
  • Estructura del proyecto
  • Detalles de autenticación
  • Desarrollo
  • Códigos de error de la API
  • Solución de problemas
  • Comunidad & soporte
  • Contribuciones
  • Enlaces rápidos

Características

• 16 herramientas MCP que cubren todos los endpoints de la API de APsystems: detalles del sistema, resúmenes de energía, datos de ECU/inversores/medidores/almacenamiento
• Autenticación por firma HMAC-SHA256 — implementa el protocolo de firma de APsystems
• Panel web integrado — aplicación de una sola página con tema oscuro y visualizaciones de energía con Chart.js
• Límite de velocidad — limitación de solicitudes configurable para respetar los límites de la API
• Reintentos automáticos — retroceso exponencial en errores transitorios y respuestas de límite de velocidad
• Transporte dual — stdio (predeterminado) o SSE sobre HTTP, seleccionable mediante variable de entorno
• Registro estructurado — registros JSON mediante slog con niveles configurables
• Soporte de Podman — Containerfile de múltiples etapas para imágenes de producción mínimas
• CI/CD — GitHub Actions para pruebas, linting y lanzamientos multiplataforma

Inicio rápido

🚀 Requisitos previos

Antes de comenzar, asegúrate de tener:

• 🦫 Go (se recomienda la última versión)
• 🔑 Credenciales de APsystems OpenAPI (APP_ID y APP_SECRET)
• 🆔 ID del sistema (SID) — Encuéntralo en la aplicación APsystems EMA en Configuración → Detalles de la cuenta

Instalación y ejecución

git clone https://github.com/mjrgr/apsystems-mcp-server.git
cd mcp-server

# Install dependencies
go mod tidy

# Set credentials
export APS_SYS_ID="your_fake_sid_1234567890"
export APS_APP_ID="your_fake_app_id_32charslong1234567890abcd"
export APS_APP_SECRET="your_fake_secret12"

# Build and run
go run ./cmd/server

Con transporte SSE

Por defecto, el servidor usa stdio (entrada/salida estándar) para la comunicación MCP. Establece APS_MCP_TRANSPORT=sse para iniciar un servidor HTTP con Server-Sent Events en su lugar:

export APS_MCP_TRANSPORT=sse
export APS_MCP_SSE_ADDR=:8888     # optional, defaults to :8888
go run ./cmd/server
# SSE endpoint: http://localhost:8888/sse
# Message endpoint: http://localhost:8888/message

Esto es útil cuando quieres conectar clientes MCP remotos a través de HTTP en lugar de ejecutar el servidor como un proceso hijo.

Con panel web

export APS_DASHBOARD=true
export APS_DASH_ADDR=:8080
go run ./cmd/server
# Dashboard available at http://localhost:8080

Demo del panel web

iniciar con Podman

podman build -t apsystems-mcp -f Containerfile .
podman run --rm \
  -e APS_SYS_ID="your_fake_sid_1234567890" \
  -e APS_APP_ID="your_fake_app_id_32charslong1234567890abcd" \
  -e APS_APP_SECRET="your_fake_secret12" \
  -e APS_DASHBOARD=true \
  -p 8080:8080 \
  apsystems-mcp

Para ejecutar con transporte SSE en lugar de stdio:

podman run --rm \
  -e APS_SYS_ID="your_fake_sid_1234567890" \
  -e APS_APP_ID="your_fake_app_id_32charslong1234567890abcd" \
  -e APS_APP_SECRET="your_fake_secret12" \
  -e APS_MCP_TRANSPORT=sse \
  -e APS_MCP_SSE_ADDR=:8888 \
  -e APS_DASHBOARD=true \
  -p 8888:8888 -p 8080:8080 \
  apsystems-mcp
# SSE endpoint: http://localhost:8888/sse

Tabla de variables de entorno

Seguridad

🔒 Mejores prácticas de seguridad

• Nunca confirmes credenciales o secretos reales de la API en el control de versiones. Usa .env.local o variables de entorno para el desarrollo local.
• Rota tu APP_SECRET y SID si sospechas que están comprometidos.
• Reporta vulnerabilidades abriendo un issue de seguridad o enviando un correo a los mantenedores.
• Para producción, usa un administrador de secretos o inyección de entorno (no archivos en texto plano).

Referencia de herramientas MCP

Herramientas del sistema

Herramientas ECU

Herramientas de inversores

Herramientas de medidores

Herramientas de almacenamiento

Uso con Claude Desktop

Uso con Claude CLI

También puedes conectar este servidor MCP a Claude CLI para acceso directo y programable a tus datos solares desde la terminal.

1. Iniciar el servidor MCP

Asegúrate de que tu servidor MCP esté en ejecución y sea accesible (local o remotamente):

go run ./cmd/server
# or with Podman/Docker as shown above

2. Configurar Claude CLI

Agrega tu servidor MCP a Claude CLI usando el comando integrado:

claude mcp add apsystems -s local -- podman run -i --rm -p 8888:8080 -e APS_DASHBOARD=true -e APS_SYS_ID=your_fake_sid_1234567890 -e APS_APP_ID=your_fake_app_id_32charslong1234567890abcd -e APS_APP_SECRET=your_fake_secret12 docker.io/mehdijrgr/apsystems-mcp-server 2>&1

claude mcp add apsystems -s local -- docker  run -i --rm -p 8888:8080 -e APS_DASHBOARD=true -e APS_SYS_ID=your_fake_sid_1234567890 -e APS_APP_ID=your_fake_app_id_32charslong1234567890abcd -e APS_APP_SECRET=your_fake_secret12 docker.io/mehdijrgr/apsystems-mcp-server 2>&1

Esto actualizará automáticamente tu configuración de Claude CLI para incluir el servidor MCP apsystems.

3. Ejemplo de uso

Pídele a Claude CLI que consulte tus datos solares a través del servidor MCP:

claude ask "Show me my solar production for today"

O usa cualquier herramienta MCP compatible, por ejemplo:

claude ask "List all my inverters"

claude ask "what's the average monthly solar production?"

¡Puedes crear scripts y automatizar consultas, integrarte con otras herramientas o usar Claude CLI en tus flujos de trabajo!

Para usar Claude Desktop con Docker o Podman, actualiza tu claude_desktop_config.json de la siguiente manera:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "aps_sys_id",
      "description": "APsystems System ID"
    },
    {
      "type": "promptString",
      "id": "aps_app_id",
      "description": "APsystems App ID"
    },
    {
      "type": "promptString",
      "id": "aps_app_secret",
      "description": "APsystems App Secret",
      "password": true
    }
  ],
  "mcpServers": {
    "apsystems": {
      "command": "podman",
      "args": [
        "run", "-i", "--rm", "-p", "8888:8080",
        "-e", "APS_DASHBOARD=true",
        "-e", "APS_SYS_ID=${input:aps_sys_id}",
        "-e", "APS_APP_ID=${input:aps_app_id}",
        "-e", "APS_APP_SECRET=${input:aps_app_secret}",
        "docker.io/mehdijrgr/apsystems-mcp-server"
      ]
    }
  }
}

O para Docker:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "aps_sys_id",
      "description": "APsystems System ID"
    },
    {
      "type": "promptString",
      "id": "aps_app_id",
      "description": "APsystems App ID"
    },
    {
      "type": "promptString",
      "id": "aps_app_secret",
      "description": "APsystems App Secret",
      "password": true
    }
  ],
  "mcpServers": {
    "apsystems": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-p", "8888:8080",
        "-e", "APS_DASHBOARD=true",
        "-e", "APS_SYS_ID=${input:aps_sys_id}",
        "-e", "APS_APP_ID=${input:aps_app_id}",
        "-e", "APS_APP_SECRET=${input:aps_app_secret}",
        "docker.io/mehdijrgr/apsystems-mcp-server"
      ]
    }
  }
}

Para transporte SSE (modo remoto/red), usa el campo url en lugar de command:

{
  "mcpServers": {
    "apsystems": {
      "url": "http://localhost:8888/sse"
    }
  }
}

También puedes montar un archivo de configuración o credenciales según sea necesario:

{
  "mcpServers": {
    "apsystems": {
      "command": "podman run -i --rm --env-file /path/to/env.local mehdijrgr/apsystems-mcp-server 2>&1",
      "env": {}
    }
  }
}

Luego pregúntale a Claude cosas como:

• "Muéstrame mi producción solar de hoy"
• "¿Cuánta energía produjo mi sistema este mes?"
• "¿Cuál es el estado de mis inversores?"
• "Compara mi producción diaria de esta semana"

Estructura del proyecto

├── cmd/server/          # CLI entry point
├── internal/
│   ├── api/             # HTTP client with auth, retries, rate limiting
│   ├── auth/            # HMAC-SHA256 signature implementation
│   ├── dashboard/       # Optional web UI (embedded HTML)
│   ├── mcp/             # MCP tool definitions and handlers
│   └── models/          # Go structs for API responses
├── .devcontainer/       # VS Code dev container config
├── .github/workflows/   # CI/CD pipelines
├── .vscode/             # Editor settings and launch configs
├── Containerfile        # Multi-stage Podman/OCI build
├── Makefile             # Build, test, lint targets
└── go.mod

Detalles de autenticación

La API de APsystems usa autenticación por firma HMAC. Cada solicitud incluye cinco encabezados personalizados:

1. X-CA-AppId — tu identificador de aplicación
2. X-CA-Timestamp — marca de tiempo Unix en milisegundos
3. X-CA-Nonce — cadena hexadecimal única de 32 caracteres (UUID sin guiones)
4. X-CA-Signature-Method — HmacSHA256
5. X-CA-Signature — Base64(HMAC-SHA256(stringToSign, appSecret))

La cadena a firmar se compone como:

timestamp/nonce/appId/requestPath/HTTPMethod/HmacSHA256

donde requestPath es el último segmento de la ruta de la URL.

Desarrollo

# Run tests
make test

# Lint
make lint

# Build for all platforms
make build

Códigos de error de la API

Solución de problemas

ℹ️ Nota: Si encuentras errores de API, verifica que tus credenciales (APP_ID, APP_SECRET, SID) sean correctas y que tu cuenta tenga habilitado el acceso a la API. Si ves errores de límite de velocidad, inténtalo de nuevo más tarde o ajusta la frecuencia de tus solicitudes.

• P: Recibo errores de 'No autorizado' o 'Cuenta de aplicación no válida'.
  • R: Vuelve a verificar tu APP_ID, APP_SECRET y SID. Asegúrate de que APsystems haya aprobado tu cuenta para el acceso a la API.
• P: Claude CLI no puede conectarse al servidor MCP.
  • R: Asegúrate de que el servidor esté en ejecución y de que la dirección/puerto coincida con tu configuración de CLI. Verifica el firewall o las asignaciones de puertos del contenedor.
• P: El panel no carga.
  • R: Asegúrate de que APS_DASHBOARD esté configurado como true y de que el servidor esté en ejecución. Visita el puerto correcto en tu navegador.

Comunidad y Soporte

• GitHub Issues — para informes de errores y solicitudes de funciones
• Discussions — para preguntas, ideas y ayuda de la comunidad
• Correo electrónico: support@apsystems.com (para solicitudes de credenciales de API)

Contribuciones

¡Las contribuciones son bienvenidas! Para comenzar:

1. Haz un fork del repositorio
2. Crea una nueva rama para tu función o corrección
3. Realiza tus cambios y añade pruebas si es necesario
4. Abre una solicitud de extracción (pull request) con una descripción clara

Consulta CONTRIBUTING.md si está disponible, o abre un issue para discutir cambios importantes primero.

Enlaces rápidos

• 📚 Documentación
• Referencia de la API
• Issues abiertos
• Discussions
• Releases
• Licencia