How do I use Octopus Energy MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Octopus Energy MCP Server show my electricity usage for last week grouped by day" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Octopus Energy MCP Server

by darronz

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Remote

Octopus Energy MCP Server

An MCP (Model Context Protocol) server for interacting with the Octopus Energy API to retrieve electricity and gas consumption data.

Features

Get electricity consumption data (kWh with 0.045 kWh precision)
Get gas consumption data (kWh for SMETS1 meters, cubic meters for SMETS2 meters)
Support for date range filtering
Pagination support
Group by day, week, month, or quarter
Order by period (ascending or descending)

Related MCP server: mcp-neso

Prerequisites

Node.js (v18 or higher recommended)
An Octopus Energy API key
Your meter details (MPAN/MPRN and serial number)

Getting Your API Key and Meter Details

API Key: Log into your Octopus Energy account at https://octopus.energy/dashboard/new/accounts/personal-details/api-access
Meter Details: You can find your MPAN (electricity) or MPRN (gas) and meter serial numbers:
- On your energy bill
- In your Octopus Energy account dashboard
- Via the Octopus Energy account API endpoint

Installation

Clone or download this repository
Install dependencies:

npm install

Create a .env file from the example:

cp .env.example .env

Edit .env and add your Octopus Energy credentials:

OCTOPUS_API_KEY=your_api_key_here
ELECTRICITY_MPAN=1234567890123
ELECTRICITY_SERIAL_NUMBER=12A3456789
GAS_MPRN=9876543210
GAS_SERIAL_NUMBER=G4A1234567

Build the project:

npm run build

Configuration

The server loads environment variables from a .env file in the project root. This file should contain:

OCTOPUS_API_KEY (required): Your API key for authentication
ELECTRICITY_MPAN (optional): Your 13-digit electricity meter point number
ELECTRICITY_SERIAL_NUMBER (optional): Your electricity meter serial number
GAS_MPRN (optional): Your 10-digit gas meter point reference number
GAS_SERIAL_NUMBER (optional): Your gas meter serial number

If you configure the meter details in .env, you won't need to provide them when calling the tools. You can still override them by passing parameters to the tools if needed.

Note: The .env file is ignored by git to keep your credentials secure.

Usage with Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "octopus-energy": {
      "command": "node",
      "args": ["/absolute/path/to/octopus-mcp-server/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/octopus-mcp-server with the actual path to this project directory.

Note: The server will automatically load your API key from the .env file in the project directory. Alternatively, you can override it by adding an env section to the config:

{
  "mcpServers": {
    "octopus-energy": {
      "command": "node",
      "args": ["/absolute/path/to/octopus-mcp-server/dist/index.js"],
      "env": {
        "OCTOPUS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

get_electricity_consumption

Retrieves electricity consumption data.

Parameters:

mpan (string, optional): The MPAN (Meter Point Administration Number). Uses ELECTRICITY_MPAN from .env if not provided.
serial_number (string, optional): The meter serial number. Uses ELECTRICITY_SERIAL_NUMBER from .env if not provided.
period_from (string, optional): Start date/time in ISO 8601 format (e.g., "2024-01-01T00:00:00Z")
period_to (string, optional): End date/time in ISO 8601 format (e.g., "2024-01-31T23:59:59Z")
page_size (number, optional): Number of results per page (default: 100, max: 25000)
order_by (string, optional): Set to "period" to return earliest records first (default: latest first)
group_by (string, optional): Group results by "day", "week", "month", or "quarter"

Example with meter details in .env:

{
  "period_from": "2024-01-01T00:00:00Z",
  "period_to": "2024-01-31T23:59:59Z",
  "group_by": "day"
}

Example with explicit parameters:

{
  "mpan": "1234567890123",
  "serial_number": "12A3456789",
  "period_from": "2024-01-01T00:00:00Z",
  "period_to": "2024-01-31T23:59:59Z",
  "group_by": "day"
}

get_gas_consumption

Retrieves gas consumption data.

Parameters:

mprn (string, optional): The MPRN (Meter Point Reference Number). Uses GAS_MPRN from .env if not provided.
serial_number (string, optional): The meter serial number. Uses GAS_SERIAL_NUMBER from .env if not provided.
period_from (string, optional): Start date/time in ISO 8601 format (e.g., "2024-01-01T00:00:00Z")
period_to (string, optional): End date/time in ISO 8601 format (e.g., "2024-01-31T23:59:59Z")
page_size (number, optional): Number of results per page (default: 100, max: 25000)
order_by (string, optional): Set to "period" to return earliest records first (default: latest first)
group_by (string, optional): Group results by "day", "week", "month", or "quarter"

Example with meter details in .env:

{
  "period_from": "2024-11-01T00:00:00Z",
  "period_to": "2024-11-30T23:59:59Z",
  "group_by": "week"
}

Example with explicit parameters:

{
  "mprn": "9876543210",
  "serial_number": "G4A1234567",
  "period_from": "2024-11-01T00:00:00Z",
  "period_to": "2024-11-30T23:59:59Z",
  "group_by": "week"
}

Response Format

Both tools return consumption data in the following format:

{
  "count": 100,
  "next": "https://api.octopus.energy/v1/...",
  "previous": null,
  "results": [
    {
      "consumption": 1.234,
      "interval_start": "2024-01-01T00:00:00Z",
      "interval_end": "2024-01-01T00:30:00Z"
    }
  ]
}

Development

Build the project:

npm run build

Run in development mode:

npm run dev

Watch for changes:

npm run watch

API Documentation

For more information about the Octopus Energy API:

Troubleshooting

"OCTOPUS_API_KEY environment variable is not set"

Make sure you've set the API key in your environment or in the Claude Desktop configuration.

Authentication errors (401)

Verify your API key is correct and active.

Invalid MPAN/MPRN or serial number

Double-check your meter details from your Octopus Energy account or bill.

Date format errors

Ensure dates are in ISO 8601 format with UTC indicator (Z suffix), e.g., "2024-01-01T00:00:00Z"

License

ISC

Available Tools

2 tools

get_electricity_consumptionA

Get electricity consumption data from Octopus Energy. Returns consumption in kWh with 0.045 kWh precision. MPAN and serial number can be provided as parameters or will use values from ELECTRICITY_MPAN and ELECTRICITY_SERIAL_NUMBER environment variables.

ParametersJSON Schema

Name	Required	Description
`mpan`	No	The MPAN (Meter Point Administration Number) for the electricity meter. Optional if ELECTRICITY_MPAN is set in .env
`serial_number`	No	The meter serial number. Optional if ELECTRICITY_SERIAL_NUMBER is set in .env
`period_from`	No	Start date/time in ISO 8601 format with UTC indicator (e.g., 2024-01-01T00:00:00Z)
`period_to`	No	End date/time in ISO 8601 format with UTC indicator (e.g., 2024-01-31T23:59:59Z)
`page_size`	No	Number of results per page (default: 100, max: 25000)
`order_by`	No	Set to 'period' to return earliest records first (default: latest first)
`group_by`	No	Group results by: day, week, month, or quarter

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses return format (kWh with precision) and parameter fallback behavior (environment variables), but doesn't mention authentication requirements, rate limits, error conditions, or whether this is a read-only operation. The description adds some behavioral context but leaves significant gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two well-structured sentences that efficiently convey purpose, return format, precision, and parameter behavior. Every sentence earns its place with no wasted words, and the most important information (what the tool does) is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter tool with no annotations and no output schema, the description provides adequate basic information about purpose and return format, but lacks details about authentication, error handling, pagination behavior (beyond page_size parameter), and what the actual response structure looks like. The schema covers parameters well, but behavioral context is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds minimal value beyond the schema by mentioning the environment variable fallback mechanism for mpan and serial_number, but doesn't provide additional semantic context for the other parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and resource ('electricity consumption data from Octopus Energy'), specifying the return unit (kWh) and precision (0.045 kWh). It distinguishes from the sibling tool 'get_gas_consumption' by explicitly mentioning electricity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use this tool (for electricity consumption data) and mentions environment variable fallbacks for parameters. However, it doesn't explicitly state when NOT to use it or provide alternatives beyond the implicit distinction from the gas consumption sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_gas_consumptionA

Get gas consumption data from Octopus Energy. Returns consumption in kWh for SMETS1 meters or cubic meters for SMETS2 meters. MPRN and serial number can be provided as parameters or will use values from GAS_MPRN and GAS_SERIAL_NUMBER environment variables.

ParametersJSON Schema

Name	Required	Description
`mprn`	No	The MPRN (Meter Point Reference Number) for the gas meter. Optional if GAS_MPRN is set in .env
`serial_number`	No	The meter serial number. Optional if GAS_SERIAL_NUMBER is set in .env
`period_from`	No	Start date/time in ISO 8601 format with UTC indicator (e.g., 2024-01-01T00:00:00Z)
`period_to`	No	End date/time in ISO 8601 format with UTC indicator (e.g., 2024-01-31T23:59:59Z)
`page_size`	No	Number of results per page (default: 100, max: 25000)
`order_by`	No	Set to 'period' to return earliest records first (default: latest first)
`group_by`	No	Group results by: day, week, month, or quarter

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it returns consumption data in different units (kWh for SMETS1, cubic meters for SMETS2), and it explains how parameters can be sourced from environment variables. This adds useful context beyond the input schema, though it could mention rate limits or error handling for completeness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose and key details. Every sentence earns its place by providing essential information without redundancy, making it efficient and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of 7 parameters, no annotations, and no output schema, the description does a good job by explaining return units and parameter sourcing. However, it lacks details on output format, error cases, or authentication needs, which would enhance completeness for a data retrieval tool with multiple options.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the input schema already documents all parameters thoroughly. The description adds minimal value by noting that MPRN and serial number can use environment variables, but it does not provide additional meaning for other parameters like period_from or group_by. This meets the baseline of 3 when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and resource ('gas consumption data from Octopus Energy'), specifying what the tool does. It distinguishes from the sibling tool 'get_electricity_consumption' by focusing on gas rather than electricity, making the purpose specific and differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning that MPRN and serial number can come from environment variables if not provided as parameters, which gives some context. However, it does not explicitly state when to use this tool versus the sibling tool or any alternatives, leaving guidance at an implied level without clear exclusions or comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

2 tool updatesv1.0.0Jan 12, 2026
- First observedget_electricity_consumption
- First observedget_gas_consumption

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation5/5

The two tools are clearly distinct: one retrieves electricity consumption data and the other retrieves gas consumption data. Their purposes do not overlap, and the descriptions specify different parameters and units, making misselection unlikely.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with 'get_' prefix and descriptive nouns ('electricity_consumption', 'gas_consumption'). The naming is uniform and predictable across the set.

Tool Count2/5

With only 2 tools, the server feels thin for an energy data domain. While it covers electricity and gas consumption, typical energy APIs might include additional operations like tariff lookup, usage analysis, or billing information, suggesting a limited scope.

Completeness2/5

The toolset is severely incomplete for an energy data server. It only provides consumption retrieval, lacking essential operations such as tariff queries, historical data analysis, account management, or update capabilities, which could hinder agent workflows.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

ClarigridOAuth
energy.clarigrid
Read-only electricity, gas, and weather data with structured provenance and units.
Energy Weather Services Open Data
13
Octopus Energy A
io.github.pipeworx-io
Octopus Energy public API MCP — UK energy tariffs & products.
Energy Open Data
352
NEM Explorer (ScadaMiner)OAuth
com.scadaminer
Query Australia's electricity market (NEM/AEMO): prices, generation, FCAS, interconnectors, bids.
Energy Open Data
2
GridHub Electricity Market Data A
io.github.jalcodev
Live and historical electricity prices and demand for 25 grids; carbon intensity for GB.
Energy Open Data
61

Related MCP Servers

Datadis MCP Server
Energy Research & Data
Jaimegruiz
A
license
Not graded
quality
C
maintenance
Enables AI agents to access and analyze Spanish electricity consumption data via the Datadis API, providing tools for supply management, consumption analysis, anomaly detection, and executive reporting.
Updated 2 months ago (2026-07-04 07:48 UTC)
MIT
mcp-nesoofficial
Energy Open Data
pipeworx-io
A
license
Not graded
quality
C
maintenance
Access Great Britain electricity grid open data from the NESO API, enabling queries about generation, demand, and market data.
Updated 13 days ago (2026-08-26 17:24 UTC)
1
MIT
mcp-octopus-energy
Energy Open Data
pipeworx-io
A
license
Not graded
quality
C
maintenance
Enables AI agents to query UK energy tariffs and products via the Octopus Energy public API.
Updated 13 days ago (2026-08-26 17:26 UTC)
16
MIT
mcp-elexon
Energy Open Data
pipeworx-io
A
license
Not graded
quality
C
maintenance
Enables access to Great Britain electricity grid and market data via the Elexon BMRS Insights API.
Updated 13 days ago (2026-08-26 17:03 UTC)
17
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/darronz/octopus-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Octopus Energy MCP Server

Features

Prerequisites

Getting Your API Key and Meter Details

Installation

Configuration

Usage with Claude Desktop

Available Tools

get_electricity_consumption

get_gas_consumption

Response Format

Development

API Documentation

Troubleshooting

"OCTOPUS_API_KEY environment variable is not set"

Authentication errors (401)

Invalid MPAN/MPRN or serial number

Date format errors

License

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Datadis MCP Server

mcp-nesoofficial

mcp-octopus-energy

mcp-elexon

Latest Blog Posts

MCP directory API