Enedis Linky MCP Server

Enedis Linky MCP Server ⚡

Um servidor Model Context Protocol (MCP) pronto para produção, escrito em Go, que encapsula a Conso API, dando a assistentes de IA como o Claude acesso direto aos dados do seu medidor inteligente Enedis Linky.

Sumário

• Enedis Linky MCP Server ⚡
  • Sumário
  • Recursos
  • Pré-requisitos
  • Início Rápido
    • 1. Compile o binário
    • 2. Defina suas credenciais
    • 3. Execute (modo stdio)
    • Execute no modo SSE
  • Uso com Claude Desktop
  • Uso com Claude CLI
    • transporte stdio
    • transporte SSE
      • 1. Prepare seu arquivo de ambiente
      • 2. Inicie o servidor
      • 3. Registre no Claude CLI
    • Exemplo de uso
  • Docker
    • Compile localmente com Podman
  • Dashboard
    • Com Docker
  • Configuração
  • Segurança
  • Referência das Ferramentas MCP
  • Estrutura do Projeto
  • Desenvolvimento
  • Solução de Problemas
  • Comunidade e Suporte
  • Contribuição
  • Licença
  • Agradecimentos

Recursos

• 5 ferramentas MCP cobrindo consumo Linky, curva de carga, potência máxima e dados de produção solar
• Autenticação por token Bearer via o proxy gratuito da Conso API
• Tentativas automáticas com backoff exponencial em erros transitórios
• Consciência de limite de requisições — respeita os limites de 5 req/s e 10k req/h
• Transportes MCP duplos — stdio para Claude Desktop, sse para clientes HTTP
• Registro estruturado — logs JSON via log/slog com níveis configuráveis
• CI/CD — GitHub Actions para testes, linting e lançamentos multiplataforma

Pré-requisitos

• 🦫 Go (versão mais recente recomendada)
• 🔑 Token da Conso API — registre-se gratuitamente em conso.boris.sh
• 🆔 Número PRM — seu identificador de medidor Linky de 14 dígitos (encontrado na sua conta de energia elétrica)

Início Rápido

1. Compile o binário

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. Defina suas credenciais

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

3. Execute (modo stdio)

./bin/enedis-linky-mcp-server

Execute no 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 com Claude Desktop

Edite o arquivo de configuração do 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"
      }
    }
  }
}

Reinicie o Claude Desktop — as ferramentas Linky aparecerão na lista de ferramentas.

Você pode então fazer perguntas como:

• "Mostre meu consumo de eletricidade na última semana"
• "Qual foi meu pico de potência neste mês?"
• "Compare meu consumo diário nos últimos 30 dias"
• "Quanta energia solar eu produzi hoje?"

Uso com Claude CLI

O servidor suporta dois transportes: stdio (padrão) e SSE (HTTP). SSE é a abordagem recomendada ao executar via Docker ou Podman, pois evita a sobrecarga do stdio em contêineres.

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

O SSE executa o servidor como um processo HTTP persistente. Inicie-o uma vez e aponte o Claude CLI para sua URL.

1. Prepare seu arquivo de ambiente

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. Inicie o 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. Registre no Claude CLI

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

Exemplo 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

Compile localmente com Podman

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

Dashboard

Ative o painel web integrado para testar sua conexão com a API e visualizar os dados do medidor diretamente no navegador — sem necessidade de 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

O painel oferece:

• Status da conexão — saúde do servidor MCP + verificação de alcance da Conso API em tempo real
• Estatísticas resumidas — kWh total, média diária, dia de pico, contagem de leituras
• Consumo Diário (gráfico de barras)
• Curva de Carga (intervalos de 30 minutos, linha)
• Potência Máxima (gráfico de barras)

Com 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

O painel roda em uma porta separada do transporte MCP SSE para que ambos possam coexistir.

Configuração

Copie .env.example para .env.local e preencha seus valores para desenvolvimento local.

Segurança

🔒 Boas Práticas de Segurança

• Nunca envie tokens de API reais para o controle de versão. Use variáveis de ambiente ou .env.local para desenvolvimento local.
• Rotacione seu token se suspeitar que ele foi comprometido — regenere-o em conso.boris.sh.
• Reporte vulnerabilidades abrindo uma issue de segurança ou enviando e-mail aos mantenedores.

Referência das Ferramentas MCP

Todas as ferramentas aceitam um PRM (identificador do medidor) e um intervalo de datas como parâmetros. O parâmetro prm é opcional quando LINKY_PRM é definido como variável de ambiente.

Estrutura do Projeto

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

Desenvolvimento

# 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 .

Solução de Problemas

ℹ️ Verifique se seu CONSO_API_TOKEN é válido e se seu PRM está autorizado na sua conta conso.boris.sh antes de relatar problemas.

• P: Recebo erros de 401 Unauthorized.
  • R: Seu token é inválido ou expirou. Regenere-o em conso.boris.sh.
• P: Recebo erros de 403 Forbidden.
  • R: Seu PRM não está autorizado na sua conta da Conso API. Certifique-se de que você o adicionou e confirmou.
• P: Nenhum dado é retornado para meu intervalo de datas.
  • R: Certifique-se de que Collecte de la consommation horaire está ativada na sua conta Enedis e que o intervalo de datas não está no futuro.
• P: O Claude CLI não consegue se conectar ao servidor MCP.
  • R: Certifique-se de que o servidor está em execução e que o endereço/porta corresponde à configuração do seu CLI. Verifique o firewall ou os mapeamentos de porta do contêiner.
• P: Recebo erros de limite de requisições.
  • R: A Conso API permite 5 req/s e 10k req/h. O servidor tenta novamente automaticamente, mas reduza a frequência de consultas se os erros persistirem.

Comunidade e Suporte

• GitHub Issues — relatórios de bugs e solicitações de recursos
• Discussions — perguntas e respostas, ideias e ajuda da comunidade

Contribuição

Contribuições são bem-vindas! Para começar:

1. Faça um fork do repositório
2. Crie um novo branch para sua funcionalidade ou correção
3. Faça suas alterações e adicione testes se necessário
4. Abra um pull request com uma descrição clara

Consulte CONTRIBUTING.md ou abra uma issue para discutir mudanças importantes primeiro.

Licença

Apache-2.0

Agradecimentos

• Conso API por Boris K — o proxy gratuito de dados Linky subjacente (GPL-3.0)
• mcp-go — SDK MCP para Go