Octopus Energy (octopus-mcp)

メモ

octopus-mcp は非公式の独立したコミュニティプロジェクトです。Octopus Energy との提携関係はなく、同社の承認やサポートも受けていません。ご自身の API キーを使って、公開されている顧客向け API に接続します。

---

「先週の電気代はいくらでしたか？今夜、食洗機を回すなら何時がよいですか？」 先週の使用量は58.4 kWh、料金は£11.92でした。このうち£2.66は基本料金で、Agile の平均単価は15.9p/kWhです。最も料金が高かったのは水曜日で、価格が30pを超えていた午後4時から午後7時の間に4.1 kWhを使用しました。今夜最も安い2時間は午前1時30分から午前3時30分で、平均単価は7.8p/kWhです。そのため、1.5 kWhの食洗機の運転にかかる費用は約12pで、今すぐ運転した場合の46pより安くなります。

エネルギーについて、普段使う言葉で質問できます。アシスタントは22個のツールから適切なものを選んで情報を調べ、許可すれば変更も行います。たとえば、次のように質問できます。

• 📊 「9月のエネルギー使用量をレポートにまとめてください。」
• ⚡ 「明日の Agile の料金はいくらですか？マイナスの料金はありますか？」
• 🕑 「家庭用バッテリーの充電に最も安い深夜の3時間を探してください。」
• 🔥 「今月のガス使用量は何 kWh ですか？」
• 🚗 「今夜、車は何時に充電されますか？明日の午前7時までに90％にしてください。」
• 🎁 「Saving Session の予定はありますか？参加登録してください。」

主な特長

• 🐳 Docker を第一に考えた、軽量な設計。 linux/amd64 と linux/arm64 に対応するイメージ（ghcr.io/mattoddie/octopus-mcp）は約 20 MB です。distroless ベース上で動作する単一の静的 Go バイナリで、シェルもパッケージマネージャーもなく、非 root ユーザーとして実行され、書き込み可能な領域もありません。長時間稼働するサービスには Streamable HTTP を、docker run -i には stdio を提供します。バイナリ単体で実行することもできます。また、Claude Desktop 用に、Docker 不要のワンクリック拡張バンドル（.mcpb）も用意しています。
• 💷 実際の料金を30分ごとに反映。 使用量の料金は、その時点で適用されていた料金プランの30分ごとの実際の単価と基本料金に基づいて計算されるため、Agile、Go、Intelligent Go、Cosy、Flux、Tracker を適切に計算できます。
• 🕑 最安の時間帯を検索。 作業に最も安い連続時間帯、その次に安い時間帯、最も安い30分枠を見つけ、今すぐ実行した場合の費用と比較します。
• 🔥 単位を正確に扱います。 SMETS2 ガスメーターは m³ で使用量を報告します。octopus-mcp はお使いのメーターの単位を把握し、標準的な計算式で換算して、どのような前提を置いたかを知らせます。
• 🛡️ デフォルトで安全。 書き込みを有効にしない限り、サーバーは読み取り専用です。許可されていないツールは登録されず、書き込みを有効にしない限り、GraphQL の生ツールはミューテーションを実行できず、トークンや API キーに触れることもありません。
• 🔑 シンプルで、シークレットを安全に扱う認証。 Octopus API キーだけで利用できます。REST リクエストではキーを直接使用し、GraphQL では有効期間の短い Kraken トークンを使います。トークンは自動的に更新され、メモリー内に保持されます。キーもトークンも出力やログに現れることはありません。
• 🎛️ 調整可能。 必要なツールセットだけを公開できるため、モデルのコンテキストを小さく、焦点の絞られた状態に保てます。
• 🧪 テスト済み。 テストスイートは、ビルドのたびに Octopus REST API と GraphQL API のモックに対して実行されます。

クイックスタート

Docker、Octopus Energy アカウント（使用量データを利用するにはスマートメーターが必要）、および Claude Code などの MCP クライアントが必要です。

1. API キーを取得します。 Octopus アカウントの Personal details → API access から取得してください。アカウント番号（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 は io.github.mattoddie/octopus-mcp として MCP Registry に掲載されているため、レジストリからインストールするクライアントは、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	電力の輸入・輸出およびガスのスマートメーター使用量を、30 分、1 時間、1 日、1 週間、1 か月単位で取得し、費用を推定します。Home Mini からのリアルタイムの需要にも対応します
tariffs	販売中のプラン、地域別の料金、30 分単位の従量料金（Agile、Go など）、基本料金、電気を使うのに最も安い時間帯、郵便番号による地域。アカウントは不要です
intelligent	Intelligent Octopus の車と充電器：ステータス、スケジュール、予定・完了済みの充電枠。書き込み機能では、目標と充電完了希望時刻の設定、充電の追加、スマート制御に対応します
octoplus	Octoplus のポイント、特典と結果を含む Saving Sessions。書き込み機能では、セッションへの参加に対応します
raw	エスケープハッチ：任意の GraphQL クエリ（ミューテーションは書き込み機能が有効な場合のみ）と、任意の 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³ 単位のガス、EV の充電、Saving Sessions
🧰 ツールリファレンス	コードから生成される、すべてのツールとプロンプト
🛡️ セキュリティ	脅威モデル、API キー、安全な書き込み設定
📡 互換性	Octopus の API、メーター、料金プラン、既知の制限
🩹 トラブルシューティング	よくあるエラーとその解決方法
🛠️ 開発	アーキテクチャ、ツールの追加、テスト

コントリビューション

バグ報告、ドキュメントの改善、新しいツールなど、コントリビューションを歓迎します。始めるにはコントリビューションガイドをお読みください。また、行動規範に従ってください。脆弱性を報告する場合は、セキュリティポリシーをご覧ください。脆弱性について公開 issue を作成しないでください。

ライセンス

MIT © Matt Oddie

octopus-mcp は独立したコミュニティプロジェクトです。Octopus Energy Ltd または Kraken Technologies Ltd との提携、承認、後援を受けていません。「Octopus Energy」、「Agile Octopus」、「Intelligent Octopus」、「Octoplus」および関連する名称は、それぞれの所有者の商標であり、このソフトウェアの対応対象を説明する目的でのみ使用しています。