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

1. API Key: Log into your Octopus Energy account at https://octopus.energy/dashboard/new/accounts/personal-details/api-access
2. 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

1. Clone or download this repository
2. Install dependencies:

npm install

3. Create a .env file from the example:

cp .env.example .env

4. 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

5. 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:

• Consumption Endpoints Documentation
• Octopus Energy Developer Portal

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