octopus-mcp

Open source · MIT · Unofficial · Model Context Protocol

Talk to your energy.

octopus-mcp connects Claude and other AI assistants to your Octopus Energy account. Ask about your usage, costs and Agile prices in plain English, find the cheapest time to run things, and let the assistant manage EV charging and Saving Sessions when you allow it.

Get started Star on GitHub
docker pull ghcr.io/mattoddie/octopus-mcp
Claude · octopus
What did electricity cost me last week, and when should I run the dishwasher tonight?
octopus_get_accountAgile · Londonoctopus_get_consumption7 days · by dayoctopus_find_cheapest_slots2 h · 1.5 kWh
Last week you used 58.4 kWh for £11.92, including standing charges: 15.9p/kWh on average. Wednesday was the priciest day, with 4.1 kWh used between 4pm and 7pm when Agile was over 30p.

Tonight the cheapest two hours are 01:30 to 03:30 at 7.8p/kWh: about 12p for the dishwasher, against 46p if you started it now.
Nice. Any Saving Sessions this week? Sign me up.
octopus_get_saving_sessionsregion Coctopus_join_saving_sessionThu 17:30
You're in for Thursday, 17:30 to 18:30, at 1,800 points per kWh saved. You usually use about 1.2 kWh then, so holding off the oven and the tumble dryer could earn you around 1,000 points. ✅
22tools
6toolsets
5guided prompts
~20 MBdistroless image

Ask anything

Your energy, in plain English.

The assistant picks the right tools, runs them against Octopus's APIs and explains what it found. No exporting CSVs or squinting at graphs in the app to find a number.

“What are the Agile prices tomorrow evening? Any negative ones?”

get_unit_rates

“When's cheapest to run the dishwasher tonight?”

get_accountfind_cheapest_slots

“How much did electricity cost me last month?”

get_accountget_consumption

“How much gas did we use this week, in kWh?”

get_consumption

“Will the car be at 80% by 7am? Make it 90%.”

get_dispatchesset_charge_preferences

“Any Saving Sessions coming up? Sign me up.”

get_saving_sessionsjoin_saving_session

Full coverage

22 tools across Octopus's APIs.

Grouped into 6 toolsets you can switch on and off, so the assistant only sees what you need: 18 read and 4 write tools.

account4

The account overview (properties, meter points with MPAN/MPRN and serial numbers, current tariffs), the balance, bills and transactions.

consumption2

Smart meter consumption for electricity import and export and gas, totalled by half-hour, hour, day, week or month with cost estimates, and live demand from a Home Mini.

tariffs6

Public tariff data: products on sale, prices by region, half-hourly unit rates (Agile, Go and others), standing charges, the cheapest times to use electricity, and the region for a postcode.

intelligent5

Intelligent Octopus: connected cars and chargers, planned and completed charging slots, and (with writes) the charging target and ready-by time, bump charges and smart control.

octoplus3

Octoplus rewards: points balance, Saving Sessions with their rewards and results, and (with writes) joining a session.

raw2

Raw API escape hatches for anything the other tools don't cover: GraphQL queries (mutations only with writes enabled) and REST GET requests.

read write ·Full tool reference →

Safe by default

It can look. It only changes things when you say so.

Octopus API keys can't be made read-only, so octopus-mcp enforces it: tools that aren't allowed aren't registered at all. The assistant can't see them, so it can't call them or be talked into calling them.

  • Read-only out of the box. One switch turns on EV charging changes and joining Saving Sessions.
  • Your key stays secret. It's never returned or logged, public price lookups don't send it, and the raw API tool can't touch tokens or keys.
  • Changes are labelled, and bump charges are marked as affecting the real world, so your client asks first.
  • Bearer-token auth, a Host allow-list and a read-only, non-root container.
Read the security model →
read

18 tools, always on

get_consumption · get_unit_rates · find_cheapest_slots · list_bills …
write

4 tools with OCTOPUS_ALLOW_WRITES=true

set_charge_preferences · bump_charge · set_smart_charging · join_saving_session
never

Not possible at all

switching tariff · payments and direct debits · personal details · your API key

Built with care

The fiddly parts, handled.

Half-hourly prices, UK time, clock changes, gas in cubic metres: octopus-mcp gets the details right so the answers are.

Real costs

Every half-hour is priced at the rate of the tariff you were on at the time, plus standing charges, so Agile, Go, Cosy and Tracker are costed properly.

Cheapest-time finder

Finds the cheapest block for a job, the runners-up and the cheapest half-hours, and says what it costs against running it now.

Honest about units

SMETS2 gas meters report m³. octopus-mcp knows which yours uses, converts with the standard formula, and says what it assumed.

Just your API key

No OAuth dance. Kraken tokens are fetched, renewed and kept in memory, and neither the key nor a token ever appears in output or logs.

Docker-first

A ~20 MB distroless image for amd64 and arm64. Non-root, read-only filesystem and no volume, because nothing is stored.

Tested against a mock Octopus

The test suite runs every tool against a mock of the REST API and both GraphQL APIs, so changes never need a real account.

5 guided prompts turn common jobs into one step. In Claude Code they're slash commands, such as /mcp__octopus__plan_cheap_usage.

  • compare_tariffs
  • energy_report
  • ev_charging_check
  • plan_cheap_usage
  • saving_session_check

Works with your Octopus account

REST and GraphQL, end to end

  • Smart meter usage
  • Cost estimates
  • Agile & time-of-use prices
  • Tariffs by region
  • Bills & balance
  • Intelligent Octopus
  • Saving Sessions
  • Home Mini live demand

Uses your own API key with Octopus's public customer APIs. Price and tariff lookups need no account at all. When a tool doesn't cover something, raw API tools do, limited to reads unless writes are on. Compatibility →

Works with your assistant

Streamable HTTP or stdio

  • Claude Code
  • Claude Desktop
  • VS Code
  • Cursor
  • Codex
  • Any MCP client

Run it once and share it, or start it per session with docker run -i. It keeps no state, so run as many as you like. Client setup →

Quick start

Up and running in three steps.

  1. 1

    Get your API key

    In your Octopus account, open Personal details → API access. Copy the API key and your account number.

  2. 2

    Start the server

    mkdir octopus-mcp && cd octopus-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/octopus-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/octopus-mcp/main/example.env -o .env
# set OCTOPUS_API_KEY, OCTOPUS_ACCOUNT
# and MCP_AUTH_TOKEN in .env
docker compose up -d
  3. 3

    Connect your assistant

    claude mcp add --transport http octopus \
  http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <token>"

    Then ask: “What's my electricity price right now?”

Ready to talk to your energy?

Free, open source and MIT licensed. Contributions and bug reports are welcome.

Read the docs Contribute