Octopus Energy (octopus-mcp)
Ask about Octopus Energy usage, Agile prices and EV charging, and join Saving Sessions
- 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.0Add 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_.RequiredOCTOPUS_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)
myIO
MCP serverAsk Claude about and control a myIO smart home controller: heating, blinds, lighting
Runs locally- 1 tool
- Open source
- Smart home
THRIVE Fleet Intelligence
MCP serverFree no-key MCP server with UK fleet data: fuel prices, EV charging, company car tax
- 15 tools
- Remote
- Free
- Energy and smart home
Spark Pack
MCP serverFree MCP tools for UK electricians: cable sizing, Part P, certificate checks and G98/G99
- 7 tools
- Remote
- Free
- Home services

ElectricityFinder
MCP serverRank Texas electricity plans by yearly cost at your own monthly usage
- 3 tools
- Remote
- Freemium
- Energy and smart home

Country energy-market bands with cited evidence, read-only for iSolOS subscribers
Not checked yet- Remote
- Paid
- Energy and smart home

Barrio Grid
MCP serverTexas grid siting data: substations, ERCOT prices, queue, parcels, water and permits
Not checked yet- 6 tools
- Remote
- Freemium
- Energy and smart home