Octopus Energy (octopus-mcp)

说明

octopus-mcp 是一个非官方的独立社区项目，与 Octopus Energy 没有任何关联，也未获其认可或支持。它使用公开的客户 API，并需要你自己的 API 密钥。

---

“上周我花了多少钱用电？今晚什么时候开洗碗机最合适？” 上周你用了 58.4 kWh，花费 £11.92，其中包括 £2.66 的固定费用；Agile 平均电价为 15.9p/kWh。周三是电价最高的一天：下午 4 点到 7 点，你用了 4.1 kWh，当时电价超过 30p。今晚最便宜的两个小时是 01:30 至 03:30，平均电价为 7.8p/kWh，因此，运行一个耗电 1.5 kWh 的洗碗机周期大约需要 12p；如果现在启动，则需要 46p。

用通俗的语言询问你的能源情况。助手会从 22 个工具中选择合适的工具来查询信息；如果你允许，也可以进行更改。示例：

• 📊 “给我一份 9 月能源用量报告。”
• ⚡ “明天的 Agile 电价是多少？有没有负电价？”
• 🕑 “找出夜间给家用电池充电最便宜的 3 个小时。”
• 🔥 “我们这个月用了多少天然气？以 kWh 计。”
• 🚗 “今晚汽车什么时候充电？明天早上 7 点前充到 90%。”
• 🎁 “即将举办 Saving Session 吗？帮我报名。”

亮点

• 🐳 Docker 优先，体积小巧。 一个镜像（ghcr.io/mattoddie/octopus-mcp）支持 linux/amd64 和 linux/arm64，大小约为 20 MB。它是在 distroless 基础镜像上运行的单个静态 Go 二进制文件，没有 shell 或包管理器，以非 root 用户身份运行，且没有可写入的内容。它可通过 Streamable HTTP 提供长期运行的服务，也可通过 docker run -i 使用 stdio。你也可以独立运行该二进制文件；对于 Claude Desktop，还有一个无需 Docker 的一键安装扩展包（.mcpb）。
• 💷 真实费用，精确到每半小时。 用电费用按你当时所用电价计划在每个半小时的实际单价计算，并计入固定费用，因此 Agile、Go、Intelligent Go、Cosy、Flux 和 Tracker 都能准确计费。
• 🕑 最低费用时段查找器。 查找执行任务费用最低的连续时段、次优时段和费用最低的半小时，并说明与立即运行相比要花费多少。
• 🔥 单位信息如实呈现。 SMETS2 燃气表报告的单位是 m³。octopus-mcp 会识别你的燃气表使用的单位，按照标准公式进行换算，并告知你它采用了什么假设。
• 🛡️ 默认安全。 除非启用写入功能，否则服务只读。未获允许的工具根本不会注册；未经启用写入功能，原始 GraphQL 工具无法执行变更，也绝不会访问令牌或 API 密钥。
• 🔑 简单且保护机密的身份验证。 只需你的 Octopus API 密钥：REST 请求直接使用该密钥，GraphQL 则使用短期 Kraken 令牌，并自动续期且仅保存在内存中。密钥和令牌都不会出现在输出或日志中。
• 🎛️ 可调节。 仅启用你需要的工具集，让模型的上下文保持精简、聚焦。
• 🧪 经过测试。 每次构建时，测试套件都会针对模拟的 Octopus REST API 和 GraphQL API 运行。

快速开始

你需要 Docker、Octopus Energy 账户（需要智能电表才能获取用量数据）和 MCP 客户端，例如 Claude Code。

1. 获取 API 密钥，前往 Octopus 账户中的 个人信息 → API 访问。同时记下你的账户编号（A-1234ABCD）。

2. 设置并启动服务。

mkdir octopus-mcp && cd octopus-mcp
curl -fsSLO https://raw.githubusercontent.com/mattoddie/octopus-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/octopus-mcp/main/example.env -o .env
# Edit .env: set OCTOPUS_API_KEY, OCTOPUS_ACCOUNT
# and a random MCP_AUTH_TOKEN (e.g. `openssl rand -hex 32`)
docker compose up -d
docker compose exec octopus-mcp /octopus-mcp status   # checks the API key

3. 连接助手。

claude mcp add --transport http octopus http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

现在，在 Claude Code 中询问 “我使用的是什么电价计划？现在的电价是多少？”。

在 Mac 或 Windows PC 上使用 Claude Desktop？ 完全不需要 Docker。从最新版本下载适用于你电脑的 .mcpb 扩展包，打开后在设置中输入 API 密钥。请参阅 Claude Desktop。

使用 VS Code、Cursor 或 Codex？请参阅连接 MCP 客户端。不想运行服务？可通过 docker run -i 或本地二进制文件使用 stdio 模式。

octopus-mcp 已列入 MCP Registry，条目为 io.github.mattoddie/octopus-mcp，因此从注册表安装的客户端可以在其中找到它及其 Docker 镜像和扩展包。

启用更改

默认情况下，助手可以查看，但不能修改。要允许它更改 Intelligent Octopus 充电设置、启动补充充电并加入 Saving Sessions，请将以下内容添加到 .env 并重启：

OCTOPUS_ALLOW_WRITES=true
OCTOPUS_TOOLSETS=account,consumption,tariffs,intelligent,octoplus   # optional: expose fewer tools

Octopus API 密钥无法限制为只读，因此这个由 octopus-mcp 强制执行的开关负责确保助手保持只读。启用前请阅读安全。若要记录助手所做的每一项更改，请将 OCTOPUS_AUDIT_LOG 设置为文件路径（参阅审计日志）。

可执行的操作

工具集	涵盖内容
account	账户概览（属性、MPAN/MPRN、电表序列号、智能电表设备 ID、当前资费）、余额、账单和交易
consumption	智能电表记录的电力输入、输出及燃气用量，按半小时、小时、天、周或月统计，并提供费用估算；来自 Home Mini 的实时需求
tariffs	在售产品、各地区价格、半小时费率（Agile、Go 等）、固定费用、最便宜的用电时段、按邮政编码查询地区。无需账户
intelligent	Intelligent Octopus 汽车和充电器：状态、计划、计划及已完成的充电时段；启用写入后，还可设置目标和就绪时间、加急充电、智能控制
octoplus	Octoplus 积分、带奖励和结果的 Saving Sessions；启用写入后，还可加入场次
raw	备用入口：执行任意 GraphQL 查询（仅启用写入后可执行 mutation）和任意 REST GET

查看 工具参考，了解所有工具和参数。现成的提示词（如 energy_report、plan_cheap_usage 和 compare_tariffs）会串联多个工具，用于处理常见任务。

文档

文档也发布在 octopus-mcp.mattoddie.dev/docs，并支持搜索。

🚀 快速入门	分步设置，从获取 API 密钥到提出第一个问题
🔌 连接 MCP 客户端	Claude Code、Claude Desktop、VS Code、Cursor、Codex、stdio 模式
⚙️ 配置	所有环境变量、身份验证机制、Docker secrets、工具集
🐳 部署	Compose、镜像标签、升级、TLS 反向代理、强化安全、无 Docker 运行
💬 使用 octopus-mcp	对话示例、提示词、单位、费用估算、以 m³ 计量的燃气、电动汽车充电、Saving Sessions
🧰 工具参考	所有工具和提示词，由代码生成
🛡️ 安全	威胁模型、API 密钥、安全的写入配置
📡 兼容性	Octopus API、电表和资费，以及已知限制
🩹 故障排除	常见错误及其解决方法
🛠️ 开发	架构、添加工具、测试

贡献

欢迎提交各种贡献，包括错误报告、文档或新工具。请阅读贡献指南以开始，并遵守行为准则。如需报告漏洞，请参阅安全政策。请勿为此公开创建 issue。

许可证

MIT © Matt Oddie

octopus-mcp 是一个独立的社区项目，与 Octopus Energy Ltd 或 Kraken Technologies Ltd 无关联，也未获其认可或赞助。“Octopus Energy”、“Agile Octopus”、“Intelligent Octopus”、“Octoplus”及相关名称均为其所有者的商标，在此仅用于描述本软件所支持的对象。