Octopus Energy Private MCPView on GitHub

Private · local · read-only

Ask better questions about your energy use.

Connect your Octopus Energy account to ChatGPT desktop or Codex in about 15 minutes. Your API credentials are read locally and sent only to Octopus Energy. Returned energy data is supplied to the AI client you choose.

Start the setup See what you need

No coding experience needed. Free and open source.

Local MCP / 01

Local credentials. Clear setup. No public MCP server.

Mac · Windows · Linux

Before you start
01

Your Octopus login

You will copy two details from your account. Your password is never needed.

02

A desktop computer

Mac, Windows, or Linux. Keep about 15 minutes free for the first setup.

03

ChatGPT desktop or Codex

The MCP runs locally and appears as a set of energy tools in your app.

Your 15-minute setup

Follow each step in order.

Nothing here changes your Octopus account. If a step does not look right, stop and use the help section before moving on.

1

About 3 minutes

Install Node.js

Node.js is the free software that runs the MCP on your computer.

  1. Open the official Node.js download page ↗.
  2. Choose the version marked LTS. Version 22 or newer is required.
  3. Download the normal installer for your computer, open it, and accept the standard options.
  4. Open Terminal on Mac or Linux, or PowerShell on Windows.
Mac

Press Command + Space, type “Terminal”, then press Return.

Windows

Open Start, type “PowerShell”, then open Windows PowerShell.

Linux

Open the Terminal app supplied with your Linux desktop.

Paste this command and press Return or Enter:

node --version
✓

You are ready when the answer begins with v22, v24, or a larger number.

2

About 2 minutes

Download the MCP

Download one ZIP file, unpack it, and put the folder somewhere permanent.

Download the latest ZIPFrom the public GitHub repository
  1. Open the downloaded ZIP file to unpack it.
  2. Move the whole unpacked folder named octopus-energy-private-mcp-main somewhere permanent. Your personal Documents folder is an easy choice, but it is not required.
  3. Keep the folder in that location. ChatGPT and Codex will later save its exact path, so moving or renaming it will break the connection until you update the saved paths.
Mac

In Finder, choose Documents in the sidebar. Its path is normally /Users/your-name/Documents.

Windows

In File Explorer, choose Documents. It may be inside your user folder or OneDrive.

Linux

Choose Documents in your file manager, or use any permanent folder inside your Home folder.

Documents is not a special MCP folder. It is simply a familiar place that is unlikely to be deleted accidentally.

Prefer Git? You can instead run git clone https://github.com/soothill/octopus-energy-private-mcp.git, but the ZIP route is simpler.

3

About 4 minutes

Prepare the MCP

Open a command window in the folder you just downloaded.

Mac The drag-and-drop way

Open Terminal. Type cd followed by one space. Drag the MCP folder from Finder into Terminal, then press Return. This does not move the folder—it inserts its full current path for you.

Windows Open PowerShell in the folder

Open the MCP folder in File Explorer. Click the address bar, type powershell, and press Enter.

Linux Open a terminal here

Open the MCP folder in your file manager, right-click an empty area, and choose “Open in Terminal”.

Run these commands one at a time. Wait for each to finish:

npm ci
npm run build
Yellow warnings are usually okay. Stop only if the final lines say npm error or that the build failed.
4

About 2 minutes

Get your Octopus details

You need an API key and account number—not your password or meter numbers.

  1. Sign in to the Octopus Developer settings page ↗.
  2. Copy your API key. It normally begins with sk_live_.
  3. Copy your account number. It begins with A- and is also shown on your bill.

Your API key is like a password. Never paste it into this website, a chat, a GitHub issue, or a screenshot. You will put it only in a file on your own computer.

5

About 2 minutes

Save the details locally

Return to the same Terminal or PowerShell window. Choose your computer below.

Mac Create and open the private settings file
cp .env.example .env
open -e .env
Windows Create and open the private settings file
Copy-Item .env.example .env
notepad .env
Linux Create and open the private settings file
cp .env.example .env
xdg-open .env

In the file, replace only the two example values at the top with your own:

OCTOPUS_API_KEY=your API key
OCTOPUS_ACCOUNT_NUMBER=your A- account number
OCTOPUS_TIMEZONE=Europe/London

Do not add quote marks or spaces around the values. Save the file and close the editor.

Windows users: make sure the file is named exactly .env, not .env.txt.

6

About 2 minutes

Connect ChatGPT desktop or Codex

ChatGPT and Codex do not search your Documents folder. This helper finds the MCP where you placed it and prints the exact, secret-free connection details for your computer:

npm run setup:codex
  1. 1

    Open the ChatGPT desktop app, then open Settings → MCP servers.

  2. 2

    Select Add server. Name it Octopus Energy and choose STDIO.

  3. 3

    Copy the printed Command, then add both printed Arguments in the same order.

  4. 4

    Save the server and select Restart when prompted.

What the saved details do: the Command starts Node.js, while the two Arguments point to this folder’s private .env file and built dist/index.js server. If you move or rename the folder later, run npm run setup:codex again, replace the saved details, and restart the app.
These steps follow the official OpenAI MCP setup guide ↗. The desktop app, Codex CLI, and IDE extension share this local configuration on the same computer. If you configure Codex directly, copy the printed [mcp_servers.octopus_energy] block into ~/.codex/config.toml. A normal ChatGPT web-browser tab cannot start this local MCP.

The moment of truth

Check that it works.

After the app restarts, type /mcp. Make sure Octopus Energy is listed and enabled, then ask these two questions.

First check

“Check my Octopus Energy connection status and explain the result in plain English.”

Then try

“Discover my Octopus Energy meters and summarise what you find. Do not include my address.”

What to ask next

Your energy data becomes a conversation.

“Analyse my electricity usage over the last 30 days and point out the busiest times.”
“Find the cheapest two-hour windows on my Agile tariff tomorrow.”
“Compare this month with the previous equivalent period.”
“How many Octoplus points do I have?”

Cost results are estimates, not bills or quotes. They cannot reproduce every discount, credit, tax, or eligibility rule on an Octopus statement.

If something does not work

Start with the simple fixes.

The full written guide includes updating and removal instructions too.

Open the complete installation guide ↗
“node” or “npm” is not recognised +

Close every Terminal or PowerShell window, restart the computer, and reinstall the LTS version from the official Node.js website.

The server says it failed to start +

Open Terminal in the MCP folder, run npm run build and npm run setup:codex, then compare the newly printed paths with the saved MCP settings.

The API key or account is missing +

Check that the local file is exactly .env, the two values have no quote marks or spaces, and the account number begins with A-. Save it and restart the app.

It works in Codex but not ChatGPT web +

That is expected. This local MCP runs on your computer, so use the ChatGPT desktop app or another local Codex client rather than a normal browser tab.

Which Documents folder should I use? +

Use the personal Documents folder shown in Finder, File Explorer, or your Linux file manager. Documents is only a suggested permanent location; the MCP can live in any folder you will keep.

I moved or renamed the MCP folder +

Open Terminal or PowerShell in its new location, run npm run setup:codex, replace the saved Command and Arguments in your MCP settings, then restart ChatGPT desktop or Codex.

I see “a newer version is available” +

If you installed with Git: open Terminal or PowerShell in the MCP folder and run git pull --ff-only, npm ci, and npm run build, then restart ChatGPT or Codex.

If you downloaded a ZIP: keep a safe copy of .env, download and unpack the latest ZIP, copy .env into the new folder, run npm ci, npm run build, and npm run setup:codex, update the saved MCP path, then restart the app.

I still need help +

Open a GitHub issue with your operating system, the failed step, the error message, and node --version. Never include your API key, account number, address, or .env file.

Privacy by design

Your API key stays out of the conversation.