MCP 服务器

Octopus Energy MCP Server

Enables retrieval of electricity and gas consumption data from Octopus Energy accounts through their API, with support for date range filtering, pagination, and grouping by time periods.

README

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)

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"
    }
  ]
}