Tool reference

octopus-mcp has 22 tools in 6 toolsets: 18 read and 4 write. It also has 5 prompts.

Each tool is labelled with the setting it needs:

Label	Registered when
🟢 read	Always
🟠 write	OCTOPUS_ALLOW_WRITES=true

Every tool also needs its toolset to be enabled in OCTOPUS_TOOLSETS, which enables all toolsets by default. Prices are in pence per kWh (unit rates) or pence per day (standing charges), including VAT; money totals are in pounds. Times are UK local time. Time arguments take YYYY-MM-DD (a whole UK day), a date and time, or now, today, yesterday and tomorrow.

Contents

• account: The account overview (properties, meter points with MPAN/MPRN and serial numbers, current tariffs), the balance, bills and transactions.
• consumption: 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.
• tariffs: 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.
• intelligent: 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.
• octoplus: Octoplus rewards: points balance, Saving Sessions with their rewards and results, and (with writes) joining a session.
• raw: Raw API escape hatches for anything the other tools don’t cover: GraphQL queries (mutations only with writes enabled) and REST GET requests.

account

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

Tool	Access	Summary
octopus_get_account	🟢 read	Account overview
octopus_get_balance	🟢 read	Account balance
octopus_list_bills	🟢 read	List bills
octopus_list_transactions	🟢 read	List transactions

octopus_get_account

🟢 read

A one-call overview of the Octopus Energy account and a good first call: each property’s address, its electricity meter points (MPAN, import or export, meter serial numbers, smart meter device IDs) and gas meter points (MPRN, serials, whether the meter reports in kWh or m³), the current tariff on each (tariff and product codes, region), the estimated annual consumption Octopus holds, and the account balance. Use the tariff codes with the tariffs tools, and the MPAN/MPRN and serials with octopus_get_consumption.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
include_balance	boolean		Include the account balance (default true)
include_history	boolean		Also list previous tariffs and properties you have moved out of
raw	boolean		Return the REST account object unchanged instead of the summary

octopus_get_balance

🟢 read

Get the account balance in pounds (positive means in credit, negative means you owe Octopus), any overdue balance and the account status.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)

octopus_list_bills

🟢 read

List the account’s bills (statements), newest first: the period covered, issue date, charges and credits, and the opening and closing balances, all in pounds. Set include_pdf_links for a temporary link to each bill’s PDF.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
from	string		Only bills issued on or after this date (YYYY-MM-DD)
include_pdf_links	boolean		Include a temporary download link for each bill’s PDF (the link expires after a short time)
limit	integer		How many to return, newest first (default 6, at most 50)
to	string		Only bills issued on or before this date (YYYY-MM-DD)

octopus_list_transactions

🟢 read

List the account’s transactions, newest first: charges for energy, payments (such as direct debits), credits (such as Octoplus rewards or Saving Session payouts) and refunds, in pounds, with the balance after each.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
from	string		Only transactions posted on or after this date (YYYY-MM-DD)
limit	integer		How many to return, newest first (default 20, at most 99)
to	string		Only transactions posted on or before this date (YYYY-MM-DD)

consumption

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.

Tool	Access	Summary
octopus_get_consumption	🟢 read	Energy consumption and cost
octopus_get_live_usage	🟢 read	Live electricity demand

octopus_get_consumption

🟢 read

Get smart meter readings for electricity (import or export) or gas, totalled by half-hour, hour, day, week or month in UK time, with an estimated cost from the tariff that was active at the time: the actual unit rate for every half-hour (so Agile, Go and other time-of-use tariffs are priced correctly) plus standing charges, including VAT. Readings come from the smart meter, usually a day behind; there is no data for meters that aren’t smart or don’t send half-hourly reads. Electricity is in kWh. SMETS2 gas meters report m³, which is converted to kWh for costing with the standard formula (m³ × 1.02264 × calorific value ÷ 3.6). For export meters the estimate is what Octopus pays you. Day/night (Economy 7) tariffs are priced assuming night hours of 00:30 to 07:30 GMT, which may not match your meter. Estimates exclude discounts and credits; your bill is the source of truth.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
calorific_value	number		Gas calorific value in MJ/m³ for converting m³ to kWh (default 39.5; your bill shows the actual value)
direction	"import" | "export"		For electricity: import (default, what you use) or export (what you send to the grid, e.g. from solar panels)
from	string		Start: a date (YYYY-MM-DD, UK time), a date and time, or today/yesterday (default 7 days ago)
fuel	"electricity" | "gas"		electricity (default) or gas
gas_units	"kwh" | "m3"		Override the units a gas meter reports in: kwh or m3 (default: as Octopus says for the meter, otherwise m3, which SMETS2 meters use)
group_by	"half_hour" | "hour" | "day" | "week" | "month" | "total"		How to total the half-hourly readings: half_hour, hour, day (default), week (Monday to Sunday), month or total
include_cost	boolean		Estimate the cost (or export earnings) from the tariff’s actual unit rates and standing charges (default true)
max_rows	integer		Return at most this many rows, the most recent (default 400); use a coarser group_by for long periods
meter_point	string		A specific MPAN (electricity) or MPRN (gas), when the account has several (see octopus_get_account)
serial	string		A specific meter serial number (default: the meter point’s meter that has readings)
to	string		End: a date (inclusive, the whole day), a date and time, or now/today/yesterday (default the end of yesterday)

octopus_get_live_usage

🟢 read

Get near real-time electricity readings from the smart meter through an Octopus Home Mini: current demand in watts and energy used in each interval. Needs a Home Mini paired with the smart meter; without one this returns no data. Readings are typically a few seconds to a few minutes old.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
device_id	string		Smart meter device ID (default: the electricity import meter’s, from octopus_get_account)
grouping	"TEN_SECONDS" | "ONE_MINUTE" | "FIVE_MINUTES" | "HALF_HOURLY" | "HOURLY"		Reading interval: TEN_SECONDS, ONE_MINUTE, FIVE_MINUTES, HALF_HOURLY or HOURLY (default ONE_MINUTE up to an hour, FIVE_MINUTES beyond)
max_rows	integer		Return at most this many readings, the most recent (default 60)
minutes	integer		How far back to look, in minutes (default 60, at most 1440)

tariffs

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.

Tool	Access	Summary
octopus_find_cheapest_slots	🟢 read	Find the cheapest times
octopus_find_region	🟢 read	Find region by postcode
octopus_get_product	🟢 read	Get product and prices
octopus_get_standing_charges	🟢 read	Standing charges
octopus_get_unit_rates	🟢 read	Unit rates
octopus_list_products	🟢 read	List Octopus products

octopus_find_cheapest_slots

🟢 read

Find the cheapest time to use electricity on a time-of-use tariff such as Agile: the cheapest continuous block of a given length (for a dishwasher, washing machine, battery or car), runner-up blocks that don’t overlap, and the cheapest individual half-hours. Only looks at prices Octopus has published (Agile prices for the next day usually appear around 4pm). Choose the tariff by tariff_code, by product_code with region or postcode, or leave them out for the account’s current tariff.

Argument	Type	Required	Description
account_number	string		With none of the above, the account’s current tariff is used: account number like A-1234ABCD (default OCTOPUS_ACCOUNT or the only account)
direction	"import" | "export"		With the account’s tariff: import (default) or export
duration_hours	number		Length of the continuous block to find, in hours, in steps of 0.5 (default 2)
from	string		Earliest start: a date and time, or now (default now)
fuel	"electricity" | "gas"		electricity (default) or gas
kwh	number		Energy the job will use, in kWh (for example 7 for a dishwasher and washing machine), to estimate its cost in the best block
postcode	string		With product_code, instead of region: a UK postcode, used to look up the region
product_code	string		Instead of tariff_code: a product code like AGILE-24-10-01 (see octopus_list_products), with region or postcode
region	string		With product_code: the region letter A to P (see octopus_find_region)
slots	integer		Also list this many of the cheapest individual half-hours, which need not be together (default 6; 0 for none)
tariff_code	string		A tariff code like E-1R-AGILE-24-10-01-C (from octopus_get_product or octopus_get_account)
to	string		Latest end: a date and time, or a date (inclusive; default as far ahead as prices are published)

octopus_find_region

🟢 read

Find which of the 14 electricity regions (A to P) a UK postcode is in. Tariff prices differ by region, and tariff codes end with the region letter. Public data; no account needed.

Argument	Type	Required	Description
postcode	string	yes	A UK postcode, for example SW1A 1AA

octopus_get_product

🟢 read

Get an Octopus product’s details and its current prices in each region, including VAT: unit rate (pence per kWh; day and night rates for Economy 7), standing charge (pence per day) and any exit fee, for electricity and gas. For half-hourly tariffs such as Agile the unit rate shown is only indicative; use octopus_get_unit_rates. Public data; no account needed.

Argument	Type	Required	Description
product_code	string	yes	Product code, like AGILE-24-10-01 or VAR-22-11-01 (see octopus_list_products)
at	string		Show the prices in force at this date (YYYY-MM-DD; default now)
postcode	string		Instead of region: a UK postcode, used to look up the region
raw	boolean		Return the API response unchanged
region	string		Only show tariffs for this region letter, A to P (default all regions)

octopus_get_standing_charges

🟢 read

Get a tariff’s daily standing charge (pence per day, including VAT): the current charge and how it has changed over a period. Choose the tariff by tariff_code, by product_code with region or postcode, or leave them out for the account’s current tariff.

Argument	Type	Required	Description
account_number	string		With none of the above, the account’s current tariff is used: account number like A-1234ABCD (default OCTOPUS_ACCOUNT or the only account)
direction	"import" | "export"		With the account’s tariff: import (default) or export
from	string		Start of the history to show (YYYY-MM-DD; default 1 year ago)
fuel	"electricity" | "gas"		electricity (default) or gas
postcode	string		With product_code, instead of region: a UK postcode, used to look up the region
product_code	string		Instead of tariff_code: a product code like AGILE-24-10-01 (see octopus_list_products), with region or postcode
region	string		With product_code: the region letter A to P (see octopus_find_region)
tariff_code	string		A tariff code like E-1R-AGILE-24-10-01-C (from octopus_get_product or octopus_get_account)
to	string		End of the history (YYYY-MM-DD, inclusive; default today)

octopus_get_unit_rates

🟢 read

Get a tariff’s unit rates (pence per kWh, including VAT) over a period: every half-hour for Agile, the cheap and peak periods for Go, Intelligent Go, Cosy and Flux, daily prices for Tracker, and the flat rate for fixed and flexible tariffs. Also gives the price now, when it next changes, and the minimum, maximum and average. Choose the tariff by tariff_code, by product_code with region or postcode, or leave them out for the account’s current tariff. Day/night tariffs list day and night rates separately.

Argument	Type	Required	Description
account_number	string		With none of the above, the account’s current tariff is used: account number like A-1234ABCD (default OCTOPUS_ACCOUNT or the only account)
direction	"import" | "export"		With the account’s tariff: import (default) or export
from	string		Start: a date (YYYY-MM-DD, UK time), a date and time, or now/today/tomorrow (default the start of today)
fuel	"electricity" | "gas"		electricity (default) or gas
max_rows	integer		Return at most this many rates (default 200)
postcode	string		With product_code, instead of region: a UK postcode, used to look up the region
product_code	string		Instead of tariff_code: a product code like AGILE-24-10-01 (see octopus_list_products), with region or postcode
region	string		With product_code: the region letter A to P (see octopus_find_region)
tariff_code	string		A tariff code like E-1R-AGILE-24-10-01-C (from octopus_get_product or octopus_get_account)
to	string		End: a date (inclusive, the whole day), a date and time, or today/tomorrow (default the end of tomorrow; Agile prices for tomorrow are usually published around 4pm)

octopus_list_products

🟢 read

List the energy products (tariffs) Octopus Energy sells now, such as Agile, Go, Intelligent Go, Cosy, Tracker, Flux, Flexible and fixed deals, with whether each is variable, a tracker, green, import or export. Public data; no account needed. Use the codes with octopus_get_product for prices.

Argument	Type	Required	Description
available_at	string		Products on sale at this date (YYYY-MM-DD; default now). Use a past date to find products that are no longer sold
brand	string		Brand code (default OCTOPUS_ENERGY)
direction	"import" | "export"		Only import or export products
include_business	boolean		Include business products (default household only)
search	string		Case-insensitive filter on the product code and names, for example agile, go, cosy, tracker, flux or fixed
variable	boolean		true for variable-price products only, false for fixed-price only

intelligent

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.

Tool	Access	Summary
octopus_bump_charge	🟠 write	Bump charge now
octopus_get_dispatches	🟢 read	Intelligent Octopus dispatches
octopus_list_devices	🟢 read	List smart devices
octopus_set_charge_preferences	🟠 write	Set charging target and ready-by time
octopus_set_smart_charging	🟠 write	Turn smart charging on or off

octopus_bump_charge

🟠 write

Start (BOOST) or cancel (CANCEL) a bump charge on an Intelligent Octopus car or charger: the car charges straight away, outside the planned smart-charging slots, so the energy is usually charged at your normal (peak) rate. Octopus refuses when the car is unplugged, away from home, already full or already boosting. Confirm with the user first.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
action	"BOOST" | "CANCEL"		BOOST (default) to start charging now, or CANCEL to stop a boost
device_id	string		The device’s ID from octopus_list_devices (default: the account’s only car or charger)

octopus_get_dispatches

🟢 read

Get Intelligent Octopus charging slots (dispatches) for a car or charger: the planned slots Octopus has scheduled (with the energy each should add) and recent completed slots. On Intelligent Octopus Go, home electricity is charged at the off-peak rate during planned smart-charging slots even outside the usual off-peak hours (Octopus caps how many hours a day this applies to; check your tariff terms). Completed slots are reported about 12 hours late.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
completed_hours	integer		How many hours of completed dispatches to include (default 24, at most 168). Octopus reports them about 12 hours late
device_id	string		The device’s ID from octopus_list_devices (default: the account’s only car or charger)

octopus_list_devices

🟢 read

List the devices Octopus controls for smart tariffs such as Intelligent Octopus Go: electric cars, chargers, batteries and heat pumps, with each one’s make and model, status (for example SMART_CONTROL_CAPABLE, BOOSTING or LOST_CONNECTION), whether smart charging is suspended, battery level where reported, and its charging schedule (target charge and ready-by time for each day).

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
device_id	string		The device’s ID from octopus_list_devices (default: the account’s only car or charger)

octopus_set_charge_preferences

🟠 write

Change an Intelligent Octopus car’s charging schedule: the battery percentage to reach and the time it must be ready by, for every day or chosen days. Days you don’t name keep their current settings. Octopus plans the next charge from these settings; the Octopus app offers ready-by times from 04:00 to 11:00 and targets in steps, and Octopus may reject other values. Confirm the change with the user first.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
days	"MONDAY" | "TUESDAY" | "WEDNESDAY" | "THURSDAY" | "FRIDAY" | "SATURDAY" | "SUNDAY"[]		Days of the week to change (default every day)
device_id	string		The device’s ID from octopus_list_devices (default: the account’s only car or charger)
ready_by	string		Time the car must be ready, as HH:MM on the hour or half-hour (the Octopus app offers 04:00 to 11:00)
target_percent	integer		Charge the battery to this percentage by the ready-by time (10 to 100)

octopus_set_smart_charging

🟠 write

Suspend or resume Intelligent Octopus smart control of a car or charger. While suspended (enabled=false), Octopus doesn’t schedule charging and the device charges according to its own settings, so home charging may not get the cheap rate. Confirm with the user first.

Argument	Type	Required	Description
enabled	boolean	yes	true to let Octopus schedule charging again; false to suspend smart charging so the device charges on its own settings
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
device_id	string		The device’s ID from octopus_list_devices (default: the account’s only car or charger)

octoplus

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

Tool	Access	Summary
octopus_get_octoplus	🟢 read	Octoplus status and points
octopus_get_saving_sessions	🟢 read	Saving Sessions
octopus_join_saving_session	🟠 write	Join a Saving Session

octopus_get_octoplus

🟢 read

Get whether the account is enrolled in Octoplus, Octopus’s rewards scheme, and its OctoPoints balance with the value Octopus gives it in pounds.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
past_limit	integer		How many past sessions you took part in to include, newest first (default 5)

octopus_get_saving_sessions

🟢 read

Get Octoplus Saving Sessions (and turn-up and weekend happy hour sessions): upcoming sessions for your region with their start and end times, the OctoPoints reward per kWh, whether you’ve joined each one and the code to join it; whether you’ve signed up to the campaign; your points balance; and results of past sessions you took part in.

Argument	Type	Required	Description
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)
past_limit	integer		How many past sessions you took part in to include, newest first (default 5)

octopus_join_saving_session

🟠 write

Join an upcoming Saving Session (or book a weekend happy hour) by its code from octopus_get_saving_sessions. Joining commits to nothing, but the reward depends on using less (or, for turn-up sessions, more) electricity than usual during the session. The account must already be signed up to Saving Sessions in Octoplus.

Argument	Type	Required	Description
event_code	string	yes	The session’s code from octopus_get_saving_sessions
account_number	string		Account number like A-1234ABCD (default OCTOPUS_ACCOUNT, or the only account the API key can see)

raw

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

Tool	Access	Summary
octopus_graphql	🟢 read	Raw GraphQL query
octopus_rest_get	🟢 read	Raw REST request

octopus_graphql

🟢 read · destructive

Run any query against Octopus’s Kraken GraphQL API (or its backend API), for anything the other tools don’t cover. The schema can be explored at https://api.octopus.energy/v1/graphql/. Most queries take accountNumber. Mutations are allowed because writes are enabled (OCTOPUS_ALLOW_WRITES=true): confirm any change with the user first. Mutations that issue or change tokens, API keys or passwords are always refused.

Argument	Type	Required	Description
query	string	yes	A GraphQL query (or, with writes enabled, a mutation). Use variables rather than pasting values into the query
endpoint	"kraken" | "backend"		kraken (default, the main Kraken API) or backend (Octopus Energy’s own API, which has Saving Sessions and Octoplus extras)
variables	object		Values for the query’s variables

octopus_rest_get

🟢 read

GET any path of the Octopus REST API (https://api.octopus.energy/v1), for anything the other tools don’t cover, such as /electricity-meter-points// or a consumption path with your own parameters. The REST API is read-only; the API key is sent with HTTP Basic auth.

Argument	Type	Required	Description
path	string	yes	Path relative to https://api.octopus.energy/v1, for example /products/ or /accounts/A-1234ABCD/
query	object		Query string parameters, for example {“period_from”: “2026-10-01T00:00Z”}

Prompts

Prompts are ready-made requests that tell the model which tools to call and what to report. In Claude Code they appear as slash commands, such as /mcp__octopus__energy_report.

compare_tariffs

Estimate what your actual recent electricity use would have cost on other Octopus tariffs, such as Agile, Go, Cosy or a fixed deal, against what you’re on now.

Argument	Required	Description
products		Product codes or names to compare (default: Agile, Go, Flexible and the cheapest fixed tariff on sale)
days		How many recent days of usage to use (default 30)

energy_report

A plain-English report on your electricity (and gas) use and cost for a period, with the tariff, the expensive times of day and ideas to save.

Argument	Required	Description
from		First day (YYYY-MM-DD; default 30 days ago)
to		Last day (YYYY-MM-DD; default yesterday)

ev_charging_check

Check an Intelligent Octopus car or charger: status, schedule, planned and recent charging slots, and anything that needs attention.

plan_cheap_usage

Find the cheapest times in the next day or so to run an appliance, charge a car or battery, on Agile or another time-of-use tariff.

Argument	Required	Description
job	yes	What needs running and roughly how long and how much energy (e.g. ‘dishwasher, 2 hours, 1.5 kWh’)
deadline		When it must be done by (e.g. ‘tomorrow 7am’; default whenever is cheapest in the published prices)

saving_session_check

See upcoming Octoplus Saving Sessions, whether you’ve joined, what you could earn, and how past sessions went.