# 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:

```bash
npm install
```

3. Create a `.env` file from the example:

```bash
cp .env.example .env
```

4. Edit `.env` and add your Octopus Energy credentials:

```env
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:

```bash
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`

```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:

```json
{
  "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:**

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

**Example with explicit parameters:**

```json
{
  "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:**

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

**Example with explicit parameters:**

```json
{
  "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:

```json
{
  "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:**

```bash
npm run build
```

**Run in development mode:**

```bash
npm run dev
```

**Watch for changes:**

```bash
npm run watch
```

## API Documentation

For more information about the Octopus Energy API:

- [Consumption Endpoints Documentation](https://developer.octopus.energy/guides/rest/api-endpoints/#consumption-endpoints)
- [Octopus Energy Developer Portal](https://developer.octopus.energy/)

## 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