# Octopus Energy (octopus-mcp)

> Octopus Energy (octopus-mcp) is an open-source MCP server for home energy. Ask about Octopus Energy usage, Agile prices and EV charging, and join Saving Sessions. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** self-hosted, macOS, Windows, Linux, CLI
- **Website:** https://octopus-mcp.mattoddie.dev
- **Repository:** https://github.com/mattoddie/octopus-mcp
- **MCP Registry name:** io.github.mattoddie/octopus-mcp
- **Categories:** home energy, energy and smart home
- **Listing updated:** 2026-11-15

## About

For UK Octopus Energy customers, this unofficial open-source server uses your own API key to expose 22 tools in six toolsets: 18 read and 4 write. It prices smart meter consumption half-hour by half-hour at the rate of the tariff you were on at the time, adds standing charges, and covers Agile, Go, Intelligent Go, Cosy, Flux and Tracker.

A cheapest-time finder picks the best continuous block for a job and compares its cost with starting now. Gas meters that report in cubic metres are converted with the standard formula and the assumption is stated. Writes, limited to Intelligent Octopus charging targets and Saving Sessions, are off unless OCTOPUS_ALLOW_WRITES is set; raw GraphQL mutations need it too, and the raw tool can never touch tokens or keys. It is not affiliated with Octopus Energy.

## Features

- **Real half-hourly costs:** Prices consumption with the tariff in force at each time.
- **Cheapest-time finder:** Finds the cheapest block for a task and compares to running it now.
- **Intelligent Octopus:** Reads charging slots and, with writes on, sets target and ready-by time.
- **Saving Sessions:** Lists sessions with rewards and results, and can join one.
- **Key stays private:** The API key and tokens are never returned or logged.

## Good for

- Check tomorrow's Agile prices for negative slots
- Find the cheapest hours to run the dishwasher
- Work out last month's electricity cost
- Convert gas usage to kWh
- Set an EV charge-by time

## Install

### Claude Code (Terminal)

```sh
claude mcp add octopus-mcp --env OCTOPUS_API_KEY='<OCTOPUS_API_KEY>' -- docker run -i --rm -e OCTOPUS_API_KEY ghcr.io/mattoddie/octopus-mcp:0.5.0
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "octopus-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OCTOPUS_API_KEY",
        "ghcr.io/mattoddie/octopus-mcp:0.5.0"
      ],
      "env": {
        "OCTOPUS_API_KEY": "<OCTOPUS_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "octopus-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OCTOPUS_API_KEY",
        "ghcr.io/mattoddie/octopus-mcp:0.5.0"
      ],
      "env": {
        "OCTOPUS_API_KEY": "<OCTOPUS_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "octopus-mcp": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OCTOPUS_API_KEY",
        "ghcr.io/mattoddie/octopus-mcp:0.5.0"
      ],
      "env": {
        "OCTOPUS_API_KEY": "<OCTOPUS_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "octopus-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OCTOPUS_API_KEY",
        "ghcr.io/mattoddie/octopus-mcp:0.5.0"
      ],
      "env": {
        "OCTOPUS_API_KEY": "<OCTOPUS_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "octopus-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "OCTOPUS_API_KEY",
        "ghcr.io/mattoddie/octopus-mcp:0.5.0"
      ],
      "env": {
        "OCTOPUS_API_KEY": "<OCTOPUS_API_KEY>"
      }
    }
  }
}
```

## FAQ

### Is it official?

No, it is an independent community project not affiliated with Octopus Energy.

### What do I need?

An Octopus account, its API key, and a smart meter for usage data.

### Can it change my account by default?

No. Writes are off unless OCTOPUS_ALLOW_WRITES is true.

### How is it distributed?

As a Docker image of about 20 MB, plus binaries and a Claude Desktop bundle.

### Is Octopus Energy (octopus-mcp) free?

Yes. Octopus Energy (octopus-mcp) is open source, so you can use and self-host it for free.

### How do I add Octopus Energy (octopus-mcp) to Claude Code?

Run this command in your terminal: claude mcp add octopus-mcp --env OCTOPUS_API_KEY='<OCTOPUS_API_KEY>' -- docker run -i --rm -e OCTOPUS_API_KEY ghcr.io/mattoddie/octopus-mcp:0.5.0

### What are the best alternatives to Octopus Energy (octopus-mcp)?

The closest alternatives to Octopus Energy (octopus-mcp) are myIO, THRIVE Fleet Intelligence, Spark Pack, ElectricityFinder and (iS)NEPI - National Energy Performance Index.

## Where this comes from

- Description: written from the project's README and the project's website.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [myIO](https://ai-powered.com/mcp/myio): myIO is an open-source MCP server for smart home.
- [THRIVE Fleet Intelligence](https://ai-powered.com/mcp/thrive-fleet-intelligence): THRIVE Fleet Intelligence is a free MCP server for energy and smart home.
- [Spark Pack](https://ai-powered.com/mcp/spark-pack): Spark Pack is a free MCP server for home services.
- [ElectricityFinder](https://ai-powered.com/mcp/electricityfinder): ElectricityFinder is a freemium MCP server for energy and smart home.
- [(iS)NEPI - National Energy Performance Index](https://ai-powered.com/mcp/is-nepi-national-energy-performance-index): (iS)NEPI - National Energy Performance Index is a paid MCP server for energy and smart home.
- [Barrio Grid](https://ai-powered.com/mcp/barrio-grid): Barrio Grid is a freemium MCP server for energy and smart home.
- [AgentDataAPI](https://ai-powered.com/mcp/agentdataapi): AgentDataAPI is a freemium MCP server for analytics and data.
- [StationSignals](https://ai-powered.com/mcp/stationsignals): StationSignals is a freemium MCP server for smart home.

---
Source: https://ai-powered.com/mcp/octopus-energy-octopus-mcp
