Enedis Linky MCP Server ⚡

A production-ready Model Context Protocol (MCP) server written in Go that wraps the Conso API, giving AI assistants like Claude direct access to your Enedis Linky smart meter data.

Table of Contents

• Enedis Linky MCP Server ⚡
  • Table of Contents
  • Features
  • Prerequisites
  • Quick Start
    • 1. Build the binary
    • 2. Set your credentials
    • 3. Run (stdio mode)
    • Run in SSE mode
  • Using with Claude Desktop
  • Using with Claude CLI
    • stdio transport
    • SSE transport
      • 1. Prepare your env file
      • 2. Start the server
      • 3. Register with Claude CLI
    • Example usage
  • Docker
    • Build locally with Podman
  • Dashboard
    • With Docker
  • Configuration
  • Security
  • MCP Tools Reference
  • Project Structure
  • Development
  • Troubleshooting
  • Community & Support
  • Contributing
  • License
  • Acknowledgements

Features

• 5 MCP tools covering Linky consumption, load curve, max power, and solar production data
• Bearer token authentication via the free Conso API proxy
• Automatic retry with exponential backoff on transient errors
• Rate-limit awareness — respects the 5 req/s and 10k req/h limits
• Dual MCP transports — stdio for Claude Desktop, sse for HTTP clients
• Structured logging — JSON logs via log/slog with configurable levels
• CI/CD — GitHub Actions for testing, linting, and cross-platform releases

Prerequisites

Log in to your Enedis customer space and enable:

• Enregistrement de la consommation horaire
• Collecte de la consommation horaire

Then register at conso.boris.sh to get your free API token and authorize your PRM.

Quick Start

1. Build the binary

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. Set your credentials

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

3. Run (stdio mode)

./bin/enedis-linky-mcp-server

Run in SSE mode

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

Using with Claude Desktop

Edit your Claude Desktop config file:

• 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"
      }
    }
  }
}

Restart Claude Desktop — the Linky tools will appear in the tool list.

You can then ask things like:

• "Show me my electricity consumption for the past week"
• "What was my peak power usage this month?"
• "Compare my daily consumption over the last 30 days"
• "How much solar energy did I produce today?"

Using with Claude CLI

The server supports two transports: stdio (default) and SSE (HTTP). SSE is the recommended approach when running via Docker or Podman as it avoids the stdio-in-container overhead.

stdio transport

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

Set CONSO_API_TOKEN and optionally LINKY_PRM in your shell environment before running.

SSE transport

SSE runs the server as a persistent HTTP process. Start it once, then point Claude CLI at its URL.

1. Prepare your env file

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. Start the server

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. Register with Claude CLI

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

Example usage

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

Build locally with Podman

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

Dashboard

Enable the built-in web dashboard to test your API connection and visualize meter data directly in the browser — no Claude client required.

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

The dashboard provides:

• Connection status — MCP server health + live Conso API reachability check
• Summary stats — total kWh, daily average, peak day, reading count
• Daily Consumption chart (bar)
• Load Curve chart (30-minute intervals, line)
• Max Power chart (bar)

With 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

The dashboard runs on a separate port from the MCP SSE transport so both can coexist.

Configuration

Copy .env.example to .env.local and fill in your values for local development.

Security

🔒 Security Best Practices

• Never commit real API tokens to version control. Use environment variables or .env.local for local development.
• Rotate your token if you suspect it is compromised — regenerate it at conso.boris.sh.
• Report vulnerabilities by opening a security issue or emailing the maintainers.

MCP Tools Reference

All tools accept a PRM (meter identifier) and a date range as parameters. The prm parameter is optional when LINKY_PRM is set as an environment variable.

Project Structure

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

Development

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

Troubleshooting

ℹ️ Check that your CONSO_API_TOKEN is valid and your PRM is authorized in your conso.boris.sh account before reporting issues.

• Q: I get 401 Unauthorized errors.
  • A: Your token is invalid or expired. Regenerate it at conso.boris.sh.
• Q: I get 403 Forbidden errors.
  • A: Your PRM is not authorized on your Conso API account. Make sure you've added and confirmed it.
• Q: No data is returned for my date range.
  • A: Ensure Collecte de la consommation horaire is enabled on your Enedis account and that the date range is not in the future.
• Q: Claude CLI can't connect to the MCP server.
  • A: Ensure the server is running and the address/port matches your CLI config. Check firewall or container port mappings.
• Q: I get rate limit errors.
  • A: The Conso API allows 5 req/s and 10k req/h. The server retries automatically, but reduce query frequency if errors persist.

Community & Support

• GitHub Issues — bug reports and feature requests
• Discussions — Q&A, ideas, and community help

Contributing

Contributions are welcome! To get started:

1. Fork the repository
2. Create a new branch for your feature or fix
3. Make your changes and add tests if needed
4. Open a pull request with a clear description

Please see CONTRIBUTING.md or open an issue to discuss major changes first.

License

Apache-2.0

Acknowledgements

• Conso API by Boris K — the underlying free Linky data proxy (GPL-3.0)
• mcp-go — Go MCP SDK