Heroku MCPサーバーでClaude Codeからアプリをデプロイ・スケーリングする

Heroku公式のMCPサーバーは、既存のHeroku CLIログインをそのまま使って接続できます。アプリ・Dyno・アドオン・パイプライン・Postgresの主要な操作を、ツールとして自然言語から呼び出せます。ツール一覧にアプリやアドオンの削除専用ツールはありませんが、所有権の移管やDyno数の変更のように、本番を直接動かすツールは揃っています。渡す権限の範囲をどこで絞るかは、利用者側の設定で決めることになります。

Heroku MCPサーバーでできること

ツールはアプリ管理・プロセス/Dyno管理・アドオン・メンテナンス/ログ・パイプライン管理・チーム/スペース管理・PostgreSQLの7カテゴリに分かれます。アプリの作成やリネーム、app.jsonによるデプロイに対応します。Dynoのスケーリングや再起動、アドオンのプロビジョニング、パイプラインのステージ昇格も対象です。PostgreSQLのクエリ実行やバックアップ管理もツールとして用意されています。

仕組みの面では、サーバーは内部でHeroku CLIを呼び出して処理します。CLIをREPLモードで常駐させるため、ツール呼び出しのたびにCLIのプロセスを起動し直さずに済みます。Renderの記事(Render MCPサーバーでClaudeからWebサービス・DBを管理する)で見た、設定変更ツールがダッシュボードへのリンクを返す設計とは対照的です。Heroku側はrename_appやtransfer_appのように、アプリの状態を直接書き換えるツールを用意しています。

アプリ管理・アドオン・チーム管理のツール

アプリ管理系では、list_appsとget_app_infoが読み取り専用です。create_appはリージョン・チーム・スペースを指定して新規アプリを作成し、rename_appは既存アプリ名を変更します。deploy_to_herokuはapp.jsonベースのデプロイに対応し、チームデプロイやプライベートスペース、環境変数の一括設定まで一度に扱えます。

アドオン管理はlist_addons・get_addon_info・create_addonの3ツールです。Dev Centerのページは用途として、アドオンの発見とアプリへの接続・切り離しを挙げています。一方READMEのツール一覧にあるのはプロビジョニングと参照だけで、切り離しや削除のツールはありません。ページ同士でこの差があるため、アドオンの付け外しをエージェントに任せたい場合は、手元のツール一覧で実際に呼べるかを先に見ておくと安心です。チーム・スペース管理はlist_teams・list_private_spacesの2ツールで、所属チームやスペースの一覧確認にとどまります。

パイプラインとログのツール

パイプライン管理はpipelines_create・pipelines_list・pipelines_info・pipelines_promoteの4ツールです。作成と一覧・詳細取得に加えて、pipelines_promoteだけがステージ間の昇格という書き込み操作を担います。ログ確認はget_app_logsで、アプリケーションログを取得できます。メンテナンスモードはmaintenance_onとmaintenance_offが対になっており、切り戻しの手段も同じツール体系の中にあります。

前提条件

Heroku CLIのバージョン10.8.1以上がグローバルにインストールされている必要があります。対応ランタイムはCommon Runtime、Cedar Private Spaces・Shield Spaces、Fir Private Spacesです。バージョンはheroku --versionで確認できます。

Private SpacesとShield Spacesは、Common Runtime(標準の共有環境)より高い分離性を求めるチーム向けの実行環境です。規制対応が必要なワークロードをHerokuで動かしている場合でも、同じMCPサーバーが対応ランタイムに含まれています。Shield Spaceのアプリも、Common Runtimeのアプリと同じ経路でツールの対象になり、askルールを入れる判断も同じです。

Claude CodeにHeroku MCPサーバーを追加する

接続方法は2通りあります。READMEが推奨するのはheroku mcp:startで、既存のHeroku CLI認証セッションをそのまま使うため、HEROKU_API_KEYを別途管理する必要がありません。

heroku mcp:start方式の追加コマンドは次のとおりです。

claude mcp add --transport stdio heroku -- heroku mcp:start

APIキー方式では、heroku authorizations:createで新規発行するか、heroku auth:tokenで既存のトークンを取得します。ダッシュボードなら、アバターからAccount Settingsを開き、ApplicationsタブのAuthorizationsでCreate authorizationを選びます。

claude mcp add --env HEROKU_API_KEY=<YOUR_HEROKU_AUTH_TOKEN> \
  --transport stdio heroku -- npx -y @heroku/mcp-server

CLIログインを使う方式で使われるのは、現在のCLIログインです。どのアカウントかはheroku auth:whoamiで確かめられるので、複数アカウントを使い分けている場合は起動前に見ておきます。

チームで共有するなら.mcp.jsonに書き出す

既定のスコープ(local)では、~/.claude.jsonにこのプロジェクト用として保存されます。リポジトリにコミットしてチームで共有するときは、--scope projectを付けます。Claude Code v2.1.289では、次のコマンドで設定が書き込まれます。

claude mcp add --scope project --transport stdio heroku -- heroku mcp:start
claude mcp add --scope project \
  --env HEROKU_API_KEY='${HEROKU_API_KEY}' \
  --env MCP_SERVER_REQUEST_TIMEOUT=30000 \
  --transport stdio heroku-api -- npx -y @heroku/mcp-server

2つ目のコマンドを実行すると、プロジェクト直下の.mcp.jsonは次の内容になります。

{
  "mcpServers": {
    "heroku": {
      "type": "stdio",
      "command": "heroku",
      "args": ["mcp:start"],
      "env": {}
    },
    "heroku-api": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": "${HEROKU_API_KEY}",
        "MCP_SERVER_REQUEST_TIMEOUT": "30000"
      }
    }
  }
}

--envの値をシェルの単一引用符で囲むと、${HEROKU_API_KEY}という参照のまま書き込まれます。実際のトークンはコミットされず、各自の環境変数から読まれます。${VAR}が未設定のまま起動すると、Claude Codeはclaude mcp listと/mcpで警告を出し、参照を展開しない文字列のままサーバーを読み込みます。

.mcp.jsonのサーバーは、初回に承認を求められます。承認前の状態はclaude mcp listとclaude mcp getでPending approvalと表示され、claudeを対話モードで起動して承認します。選択をやり直したいときはclaude mcp reset-project-choicesを使います。

本番操作に関わるツールと権限の境界

削除に匹敵する影響を持つツールは複数あります。

deploy_one_off_dynoはファイル作成・ネットワークアクセス・環境変数の指定に対応し、実行後は自動でクリーンアップされます。スクリプトの動作確認には便利な一方、実行内容そのものはAIが組み立てるコードです。ネットワークアクセスを許可した状態で使う場合、渡すコマンドの中身を確認してから実行する運用が安全です。

DynoまわりはProcess & Dyno管理という別カテゴリで、ps_list・ps_scale・ps_restartの3ツールがあります。ps_scaleはDyno数の増減だけでなく、Dynoのサイズ変更も一つのツールで担います。ps_restartは特定のプロセスタイプ・特定のDyno・全Dynoのいずれを対象にするかを選べるため、対象範囲の指定を誤ると想定より広い範囲を再起動してしまいます。

READMEとDev Centerのページは、このMCPサーバーが早期開発段階にあり、提供される機能やツールが今後変わりうると述べています。バージョンアップのたびにツール一覧を見直す前提で使います。

Postgresツール群の権限範囲

PostgreSQL関連のツールは10種類あり、pg_psqlはHeroku Postgresに対してSQLクエリを実行するツールです。READMEとDev Centerのツール一覧は「SQLクエリを実行」とだけ説明しており、読み取り専用とは書いていません。Renderのquery_render_postgresが読み取り専用SQLに絞っているのとは性格が異なります。更新系のSQLも通る前提で扱います。

• pg_psql: SQLクエリを実行
• pg_kill: 特定のデータベースプロセスを終了
• pg_upgrade: PostgreSQLを新しいバージョンへアップグレード
• pg_backups: バックアップとそのスケジュールの管理
• pg_credentials: データベースの認証情報とアクセスの管理

残るpg_info(DB詳細情報の表示)・pg_ps(実行中クエリの確認)・pg_locks(ロックとブロッキングトランザクションの確認)・pg_outliers(リソース消費の大きいクエリの特定)・pg_maintenance(メンテナンス情報の表示)は、いずれも参照系です。

集計クエリを投げるだけの用途でも、pg_psqlは更新系のSQLを実行できるツールのままです。この絞り込みはClaude Codeの権限ルールで行えます。MCPツールのaskルールはmcp__<サーバー名>__<ツール名>の形で書き、上の手順でサーバー名をherokuにした場合は次のようになります。

{
  "permissions": {
    "ask": [
      "mcp__heroku__pg_psql",
      "mcp__heroku__pg_kill",
      "mcp__heroku__pg_upgrade",
      "mcp__heroku__pipelines_promote",
      "mcp__heroku__transfer_app",
      "mcp__heroku__ps_scale",
      "mcp__heroku__maintenance_on",
      "mcp__heroku__deploy_one_off_dyno"
    ]
  }
}

askに入れたツールは、呼ぶたびに承認プロンプトが出ます。逆にサーバー全体を許可したいときだけmcp__heroku__*のようなワイルドカードをallowに書けます。server:tool単位の書き方の詳細はClaude Code MCP権限ルールにあります。

タイムアウトの調整

コマンド実行のタイムアウトは、MCP_SERVER_REQUEST_TIMEOUT環境変数で指定します。単位はミリ秒で、未設定なら15000(15秒)です。処理に15秒以上かかるツールを使うときは、値を伸ばしておきます。HEROKU_API_KEYと並べてenvに置けるので、前掲の.mcp.jsonのheroku-apiの例がそのまま使えます。

READMEの環境変数の設定例はnpx方式のものだけで、heroku mcp:start方式で同じ環境変数を渡す例は載っていません。タイムアウトを変えたい場合は、設定例のあるAPIキー方式を使うと迷いません。

読み取り系と書き込み系、実際のプロンプトの違い

障害調査や状態確認で使う典型的なプロンプトは読み取り系のツールに閉じます。

• 「本番アプリのDyno一覧とステータスを教えて」→ps_list(読み取り専用)
• 「直近のアプリケーションログを見せて」→get_app_logs(読み取り専用)
• 「重いクエリを実行しているプロセスを教えて」→pg_outliers・pg_ps(読み取り専用)

一方、次のようなプロンプトは書き込み系のツールを呼びます。

• 「stagingアプリをproductionパイプラインに昇格して」→pipelines_promote(本番に直結)
• 「Webのdynoを3台にスケールして」→ps_scale(コストと可用性に影響)
• 「このアプリをteam-Bに移管して」→transfer_app(所有権の移動)

同じ会話の中で読み取り系と書き込み系が連続して呼ばれることも多いため、書き込み系ツールの名前を事前に把握しておくと、承認プロンプトで立ち止まる判断がしやすくなります。

よくあるつまずき

heroku mcp:start方式でツールが失敗するときは、まずCLIのログイン状態を見ます。heroku auth:whoamiでログイン中のアカウントを確認し、切れていればheroku loginをやり直します。

チームやスペースをまたいでアプリを管理している場合、READMEによるとlist_appsはpersonal・collaborator・team・spaceで絞り込めるので、対象のアプリだけを一覧に出してから操作します。

ツール名や挙動が想定と違うときは、MCP Inspectorで実際に呼べるツール一覧を見ると切り分けが早くなります。READMEのnpx @modelcontextprotocol/inspector heroku-mcp-serverは、ソースを取得してnpm linkでグローバルCLIとして登録した開発者向けの手順です。インストール済みの環境で試すなら、Inspectorに起動コマンドをそのまま渡します。

npx @modelcontextprotocol/inspector heroku mcp:start

まとめ

手元のCLIログインで使うならheroku mcp:start、CIのようにログインを持ち込めない場所ならHEROKU_API_KEYを${HEROKU_API_KEY}の参照で渡す方式が合います。どちらでも、pg_psql・pipelines_promote・transfer_app・ps_scaleはaskに入れておくと、読み取り系の作業を止めずに済みます。他のPaaS向けMCPサーバーとの権限設計の違いは、PaaS系MCPの本番デプロイ権限を各社でどう絞るかで比較しています。LaravelアプリをClaude Codeで作ってからHerokuに載せる場合は、Claude CodeでLaravelアプリを開発するも参考になります。Railsアプリの開発からHerokuへのデプロイまでの手順は、Claude CodeでRailsアプリを開発する手順とscaffoldの使い分けで扱っています。