Octopus Energy

You can run an MCP server that talks to the Octopus Energy API to fetch electricity and gas consumption data. It exposes tools to query consumption over date ranges, group results by period units, and paginate large result sets so you can build dashboards or carry out analyses with precise, structured data.

How to use

Start the MCP server as a local process and connect to it with an MCP client. The server exposes two primary tools for data retrieval: electricity consumption and gas consumption. Use your MCP client to request data by supplying meter details when you want to override defaults, or rely on the preconfigured values loaded from your environment. You can filter results by period_from and period_to, control how many records you receive with page_size, decide the ordering with order_by, and group results by day, week, month, or quarter. The response includes a count and a list of consumption records with interval_start and interval_end timestamps.

Typical usage patterns include retrieving daily electricity consumption for a month to populate a chart, or fetching weekly gas consumption grouped by week for a billing estimate. If you already configured meter details in your environment, you can omit repeating them in every request; you can still override them by passing explicit parameters to the tools when needed.

How to install

Prerequisites you need on your machine: Node.js v18 or higher, an Octopus Energy API key, and your meter details (MPAN/MPRN and serial numbers). Then follow these steps to install and prepare the server.

1. Get the code locally by cloning or downloading the project.

2. Install dependencies.

npm install

3. Create a configuration file from the example and edit it with your credentials.

4. Build the project so the runtime artifacts are available for execution.

npm run build

5. Run the server in development or production mode as described in the runtime instructions. The server will load credentials from the environment by default, but you can override them via an explicit environment block in your MCP client configuration.

Configuration and security

Environment variables are loaded from a file at the project root. The required and optional variables are as follows.

• OCTOPUS_API_KEY (required): Your Octopus Energy API key.

• ELECTRICITY_MPAN (optional): Your 13-digit electricity MPAN.

• ELECTRICITY_SERIAL_NUMBER (optional): Your electricity meter serial number.

• GAS_MPRN (optional): Your 10-digit gas MPRN.

• GAS_SERIAL_NUMBER (optional): Your gas meter serial number.

These values can be set in the environment file or overridden in the MCP client configuration when you start the server.

Troubleshooting

If you see an error indicating that the API key is not set, verify that OCTOPUS_API_KEY is provided in your environment or in your MCP client’s config.

Authentication errors (401) usually mean the API key is invalid or not active. Double-check the key in your Octopus Energy account.

Ensure your meter details (MPAN/MPRN and serial numbers) are correct and correspond to your Octopus Energy account.

Date formats must use ISO 8601 with UTC time (for example, 2024-01-01T00:00:00Z). If you see date parsing errors, review the period_from and period_to values.

Development

Build the project, then run in development mode to test locally.

npm run build

npm run dev

npm run watch

Available tools

get_electricity_consumption

Retrieves electricity consumption data with optional MPAN, serial number, date range, pagination, ordering, and grouping.

get_gas_consumption

Retrieves gas consumption data with optional MPRN, serial number, date range, pagination, ordering, and grouping.