MCP 服务器

octopus-mcp

Lets Claude analyse your Octopus Energy account: usage, costs, tariff comparisons, Saving Sessions, Octoplus rewards.

README

octopus-mcp

Unofficial. Not affiliated with Octopus Energy. Uses the public REST API and the community-known Kraken GraphQL endpoint; the latter is unofficial and may break without notice.

A Model Context Protocol server that lets Claude analyse your Octopus Energy account: usage, costs, tariff comparisons, Saving Sessions, Octoplus rewards.

Works with Claude Code, Claude Desktop, and any MCP-compatible client.

Prerequisites

Python 3.11 or newer
An Octopus Energy account in the UK
A smart meter sending half-hourly readings (so consumption data is available via the API)

Install

The server is published on PyPI as octopus-mcp. You can install it with uv (recommended) or plain pip.

With `uv` (recommended)

If you don't have uv yet:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then install the MCP server and save credentials:

uv tool install octopus-mcp
octopus-mcp configure   # interactive; writes to your OS keychain

With `pip`

pip install octopus-mcp
octopus-mcp configure

Wire it into your MCP client

Claude Code

In Claude Code, register this repo as a plugin marketplace and install the octopus plugin from it:

/plugin marketplace add DanielChicot/octopus-mcp
/plugin install octopus@octopus-mcp

The plugin auto-registers the MCP server (no manual config-file edits needed) and adds four slash commands (/octopus:bill, /octopus:compare, /octopus:peaks, /octopus:saving-sessions) plus an analysis skill that Claude triggers automatically on energy-related questions.

Claude Desktop, Cursor, and other MCP clients

Add this entry to your client's MCP config:

{
  "mcpServers": {
    "octopus": {
      "command": "uvx",
      "args": ["octopus-mcp"]
    }
  }
}

(If you installed with pip instead of uv, replace "command": "uvx", "args": ["octopus-mcp"] with "command": "octopus-mcp", "args": ["serve"].)

The config file lives at:

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Restart your MCP client after editing the config.

Credentials

You need:

OCTOPUS_API_KEY — find at octopus.energy → My account → Personal details → Developer settings
OCTOPUS_ACCOUNT_NUMBER — A-XXXXXXXX, on any bill or in your account

Optional (only some Kraken queries):

OCTOPUS_EMAIL / OCTOPUS_PASSWORD

Resolution order: shell env > .env > OS keyring > error. The recommended path is octopus-mcp configure which writes to the OS keyring so secrets never sit in plaintext config.

Tools

Tool	What it does
`bill_summary(period)`	Total kWh and £ per fuel for a period
`usage_breakdown(period, group_by)`	Aggregated kWh by hour/day/week/month
`peak_hours(period, top_n)`	Top-N highest-usage half-hours
`compare_tariff(target_product_code, period, fuel)`	Replay your usage against another Octopus tariff
`current_tariff()`	What you're on now: unit rate, standing charge
`saving_session_history()`	Octoplus saving sessions joined and rewards earned
`get_account()`, `list_products()`, `get_product()`, `get_consumption_raw()`, `kraken_query()`	Thin getters / escape hatches

Slash commands (Claude Code plugin)

/octopus:bill [period] — bill summary as a markdown table
/octopus:compare <product-code> [period] — tariff comparison with caveats
/octopus:peaks [period] [top_n] — highest-usage half-hours
/octopus:saving-sessions — Octoplus history

How it works

A SQLite cache at ~/Library/Caches/octopus-mcp/ (or your platform's equivalent) holds your historical consumption and tariff data, refreshed incrementally.
All cost figures are in integer pence inc-VAT (no float drift), with a derived pounds string for display.
Tariff comparison is a pure tariff swap model — caveats list what it does and doesn't model. See the design doc.

Known limitations (v0.1)

Gas SMETS2 m³ vs kWh: if your gas meter reports in m³, values won't be normalised — expect implausibly small numbers and multiply by ~11.18 to convert. v0.2 will detect and apply calorific conversion automatically.
Region-aware tariff lookup: compare_tariff currently picks the first region's tariff variant from a target product. v0.2 will use your postcode-derived region.
TTLs are hardcoded: no config.toml support yet.
No background sync: consumption is fetched lazily on demand.

Privacy

The MCP runs on your machine. No data leaves your computer except direct calls to api.octopus.energy. Credentials live in your OS keychain. Logs at ~/Library/Logs/octopus-mcp/server.log redact secrets.