Enedis Linky MCP Server

Servidor MCP Enedis Linky ⚡

Un servidor Model Context Protocol (MCP) listo para producción, escrito en Go, que envuelve la Conso API, brindando a asistentes de IA como Claude acceso directo a los datos de tu medidor inteligente Enedis Linky.

Tabla de Contenidos

• Servidor MCP Enedis Linky ⚡
  • Tabla de Contenidos
  • Características
  • Requisitos Previos
  • Inicio Rápido
    • 1. Compilar el binario
    • 2. Configurar tus credenciales
    • 3. Ejecutar (modo stdio)
    • Ejecutar en modo SSE
  • Uso con Claude Desktop
  • Uso con Claude CLI
    • Transporte stdio
    • Transporte SSE
      • 1. Prepara tu archivo de entorno
      • 2. Inicia el servidor
      • 3. Regístrate con Claude CLI
    • Ejemplo de uso
  • Docker
    • Compilar localmente con Podman
  • Panel de Control
    • Con Docker
  • Configuración
  • Seguridad
  • Referencia de Herramientas MCP
  • Estructura del Proyecto
  • Desarrollo
  • Solución de Problemas
  • Comunidad y Soporte
  • Contribuciones
  • Licencia
  • Agradecimientos

Características

• 5 herramientas MCP que cubren consumo Linky, curva de carga, potencia máxima y datos de producción solar
• Autenticación por token Bearer a través del proxy gratuito Conso API
• Reintentos automáticos con retroceso exponencial ante errores transitorios
• Conciencia de límites de tasa — respeta los límites de 5 req/s y 10k req/h
• Transportes MCP duales — stdio para Claude Desktop, sse para clientes HTTP
• Registro estructurado — registros JSON vía log/slog con niveles configurables
• CI/CD — GitHub Actions para pruebas, linting y lanzamientos multiplataforma

Requisitos Previos

• 🦫 Go (se recomienda la última versión)
• 🔑 Token de Conso API — regístrate gratis en conso.boris.sh
• 🆔 Número PRM — tu identificador de medidor Linky de 14 dígitos (se encuentra en tu factura de electricidad)

Inicio Rápido

1. Compilar el binario

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

go mod download
make build
# Binary is at ./bin/enedis-linky-mcp-server

2. Configurar tus credenciales

export CONSO_API_TOKEN="your_token_here"
export LINKY_PRM="12345678901234"   # optional but recommended

3. Ejecutar (modo stdio)

./bin/enedis-linky-mcp-server

Ejecutar en modo SSE

export MCP_TRANSPORT=sse
export PORT=8080
./bin/enedis-linky-mcp-server
# Listening on :8080 — point your MCP client at http://localhost:8080/sse

Uso con Claude Desktop

Edita tu archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "linky": {
      "command": "/absolute/path/to/bin/enedis-linky-mcp-server",
      "env": {
        "CONSO_API_TOKEN": "your_token_here",
        "LINKY_PRM": "12345678901234"
      }
    }
  }
}

Reinicia Claude Desktop — las herramientas de Linky aparecerán en la lista de herramientas.

Luego puedes hacer preguntas como:

• "Muéstrame mi consumo de electricidad de la última semana"
• "¿Cuál fue mi uso máximo de potencia este mes?"
• "Compara mi consumo diario de los últimos 30 días"
• "¿Cuánta energía solar produje hoy?"

Uso con Claude CLI

El servidor admite dos transportes: stdio (predeterminado) y SSE (HTTP). SSE es el enfoque recomendado cuando se ejecuta mediante Docker o Podman, ya que evita la sobrecarga de stdio en contenedores.

Transporte stdio

claude mcp add linky -s local -- docker run -i --rm \
  -e CONSO_API_TOKEN=your_token_here \
  -e LINKY_PRM=12345678901234 \
  ghcr.io/mjrgr/enedis-linky-mcp-server:latest

claude mcp add linky -s local -- /absolute/path/to/bin/enedis-linky-mcp-server

Transporte SSE

SSE ejecuta el servidor como un proceso HTTP persistente. Inícialo una vez y luego apunta Claude CLI a su URL.

1. Prepara tu archivo de entorno

cp .env.example .env.local
# Edit .env.local — set CONSO_API_TOKEN, LINKY_PRM, and MCP_TRANSPORT=sse

CONSO_API_TOKEN=your_token_here
LINKY_PRM=12345678901234
MCP_TRANSPORT=sse
PORT=8080

2. Inicia el servidor

docker run --rm \
  --env-file .env.local \
  -p 8080:8080 \
  ghcr.io/mjrgr/enedis-linky-mcp-server:latest

podman build -t enedis-linky-mcp -f Containerfile .
podman run --rm \
  --env-file .env.local \
  -p 8080:8080 \
  enedis-linky-mcp

3. Regístrate con Claude CLI

claude mcp add linky --transport sse http://localhost:8080/sse

Ejemplo de uso

claude "Show me my electricity consumption for today"

claude "What's my average daily power usage this week?"

Docker

docker run --rm \
  --env-file .env.local \
  -p 8080:8080 \
  ghcr.io/mjrgr/enedis-linky-mcp-server:latest

Compilar localmente con Podman

podman build -t enedis-linky-mcp -f Containerfile .
podman run --rm \
  --env-file .env.local \
  -p 8080:8080 \
  enedis-linky-mcp

Panel de Control

Habilita el panel de control web integrado para probar tu conexión API y visualizar los datos del medidor directamente en el navegador — sin necesidad de un cliente Claude.

export CONSO_API_TOKEN=your_token_here
export LINKY_DASHBOARD=true
export LINKY_PRM=12345678901234   # optional — pre-fills the PRM field in the dashboard
./bin/enedis-linky-mcp-server
# Dashboard available at http://localhost:8081

El panel de control proporciona:

• Estado de conexión — salud del servidor MCP + verificación de alcance de Conso API en vivo
• Estadísticas resumidas — kWh totales, promedio diario, día pico, número de lecturas
• Gráfico de Consumo Diario (barras)
• Gráfico de Curva de Carga (intervalos de 30 minutos, línea)
• Gráfico de Potencia Máxima (barras)

Con Docker

docker run --rm \
  -e CONSO_API_TOKEN=your_token_here \
  -e LINKY_PRM=12345678901234 \
  -e LINKY_DASHBOARD=true \
  -e MCP_TRANSPORT=sse \
  -p 8080:8080 \
  -p 8081:8081 \
  ghcr.io/mjrgr/enedis-linky-mcp-server:latest

El panel de control se ejecuta en un puerto separado del transporte SSE de MCP para que ambos puedan coexistir.

Configuración

Copia .env.example a .env.local y completa tus valores para el desarrollo local.

Seguridad

🔒 Mejores Prácticas de Seguridad

• Nunca comprometas tokens API reales en el control de versiones. Usa variables de entorno o .env.local para el desarrollo local.
• Rota tu token si sospechas que está comprometido — regenéralo en conso.boris.sh.
• Reporta vulnerabilidades abriendo un problema de seguridad o enviando un correo a los mantenedores.

Referencia de Herramientas MCP

Todas las herramientas aceptan un PRM (identificador de medidor) y un rango de fechas como parámetros. El parámetro prm es opcional cuando LINKY_PRM se configura como variable de entorno.

Estructura del Proyecto

enedis-linky-mcp-server/
├── cmd/
│   └── server/
│       └── main.go            # Entrypoint — wires config, client, service, MCP server
├── internal/
│   ├── config/
│   │   └── config.go          # ENV-based configuration with validation
│   ├── client/
│   │   └── client.go          # Typed HTTP client — retry, backoff, User-Agent
│   ├── service/
│   │   └── service.go         # Business logic — validation, aggregation
│   └── mcp/
│       ├── server.go          # MCP server lifecycle (stdio / SSE transport)
│       └── tools.go           # Tool definitions & handlers
├── .github/
│   └── workflows/
│       ├── ci.yml             # lint → test → build
│       └── release.yml        # GoReleaser + Docker (triggered on tags)
├── Containerfile              # Multi-stage, distroless final image
├── Makefile                   # Developer shortcuts
├── .env.example               # Configuration template
└── go.mod

Desarrollo

# Install dependencies
go mod download

# Run tests
make test

# Lint
make lint

# Build for all platforms
make build

# Build container image
podman build -f Containerfile .

Solución de Problemas

ℹ️ Verifica que tu CONSO_API_TOKEN sea válido y que tu PRM esté autorizado en tu cuenta de conso.boris.sh antes de reportar problemas.

• P: Recibo errores de 401 Unauthorized.
  • R: Tu token no es válido o ha expirado. Regénalo en conso.boris.sh.
• P: Recibo errores de 403 Forbidden.
  • R: Tu PRM no está autorizado en tu cuenta de Conso API. Asegúrate de haberlo agregado y confirmado.
• P: No se devuelven datos para mi rango de fechas.
  • R: Asegúrate de que Collecte de la consommation horaire esté habilitado en tu cuenta de Enedis y que el rango de fechas no esté en el futuro.
• P: Claude CLI no puede conectarse al servidor MCP.
  • R: Asegúrate de que el servidor esté ejecutándose y que la dirección/puerto coincida con tu configuración de CLI. Verifica el firewall o las asignaciones de puertos del contenedor.
• P: Recibo errores de límite de tasa.
  • R: La Conso API permite 5 req/s y 10k req/h. El servidor reintenta automáticamente, pero reduce la frecuencia de consultas si los errores persisten.

Comunidad y Soporte

• Problemas de GitHub — reportes de errores y solicitudes de funciones
• Discusiones — preguntas y respuestas, ideas y ayuda de la comunidad

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 agrega pruebas si es necesario
4. Abre una solicitud de extracción con una descripción clara

Consulta CONTRIBUTING.md o abre un problema para discutir cambios importantes primero.

Licencia

Apache-2.0

Agradecimientos

• Conso API por Boris K — el proxy gratuito subyacente de datos Linky (GPL-3.0)
• mcp-go — SDK MCP de Go