Skip to content
MCP server

Octopus Energy (octopus-mcp)

Ask about Octopus Energy usage, Agile prices and EV charging, and join Saving Sessions

Runs locallyStatus and history
Pricing
Open source
Platforms
self-hosted, macOS, Windows
Runs
Locally
Version
0.4.0
Listing updated
2 days ago

About Octopus Energy (octopus-mcp)

Octopus Energy (octopus-mcp) is an open-source MCP server for home energy. It runs locally on your machine and is started by your AI client.

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.

Install

Run in a 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.4.0

Add to claude_desktop_config.json

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

Add to ~/.cursor/mcp.json

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

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Configuration

  • MCP_TRANSPORTThe image serves HTTP by default; this runs it over stdio.
  • OCTOPUS_API_KEYYour Octopus API key, from Personal details → API access in your Octopus account. It starts sk_live_.Required
  • OCTOPUS_ACCOUNTYour account number, like A-1234ABCD. Optional when the key can see only one account.
  • OCTOPUS_ALLOW_WRITEStrue lets the assistant change Intelligent Octopus charging and join Saving Sessions. false is read-only.
  • OCTOPUS_TOOLSETSComma-separated toolsets to expose: account, consumption, tariffs, intelligent, octoplus, raw. Empty means all, which leaves out raw: name it (all,raw) to enable it.
  • OCTOPUS_AUDIT_LOGstderr, or a file path, to record every change the assistant makes as a JSON line. A file needs a volume.

What it does

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

Pricing

Open source

MIT licence; an Octopus Energy account is required

Prices change. Check octopus-mcp.mattoddie.dev before you buy.

Octopus Energy (octopus-mcp) 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.4.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.

Alternatives to Octopus Energy (octopus-mcp)

  1. myIO

    MCP server

    Ask Claude about and control a myIO smart home controller: heating, blinds, lighting

    Runs locally
    • 1 tool
    • Open source
    • Smart home
  2. Free no-key MCP server with UK fleet data: fuel prices, EV charging, company car tax

    • 15 tools
    • Remote
    • Free
    • Energy and smart home
  3. Spark Pack

    MCP server

    Free MCP tools for UK electricians: cable sizing, Part P, certificate checks and G98/G99

    • 7 tools
    • Remote
    • Free
    • Home services
  4. Rank Texas electricity plans by yearly cost at your own monthly usage

    • 3 tools
    • Remote
    • Freemium
    • Energy and smart home
  5. Barrio Grid

    MCP server

    Texas grid siting data: substations, ERCOT prices, queue, parcels, water and permits

    Not checked yet
    • 6 tools
    • Remote
    • Freemium
    • Energy and smart home