heroku-mcp-server

heroku-mcp-server

Heroku Platform MCP Server は、Common Runtime、Cedar Private および Shield Spaces、ならびに Fir Private Spaces で動作します。

前提条件

• Heroku CLI がシステムにグローバルインストールされている必要があります。バージョンは 10.8.1 以降です。
  • Heroku CLI のインストールまたはアップグレード

Heroku にデプロイ

概要

Heroku Platform MCP Server は、LLM と Heroku Platform のシームレスな連携を実現するために設計された、Model Context Protocol（MCP）の特化型実装です。このサーバーは、LLM が Heroku Platform のリソースを読み取り、管理、操作するための堅牢なツールと機能を提供します。

主な機能：

• LLM 主導のツールを通じて Heroku Platform のリソースと直接連携
• Heroku CLI を活用した、Heroku Platform API への安全で認証済みのアクセス
• Heroku Platform と連携するための自然言語インターフェース

注：Heroku Platform MCP Server は現在、開発初期段階にあります。実装の強化と改良を続ける中で、利用可能な機能やツールは変更される可能性があります。このプロジェクトの今後の方向性を形作るため、フィードバックや貢献をお待ちしています。

注： Heroku Platform MCP Server を使用するには、Heroku CLI がグローバルにインストールされている必要があります（v10.8.1 以降）。heroku --version を実行して、適切なバージョンであることを確認してください。

Heroku Platform MCP Server の設定

Claude Desktop、Zed、Cursor、Windsurf などのクライアントを、Heroku Platform MCP Server と連携するように設定できます。

heroku mcp:start を使用した Heroku Platform MCP Server の設定

heroku mcp:start を使用して Heroku Platform MCP Server を起動します。この方法は既存の Heroku CLI 認証を利用するため、HEROKU_API_KEY 環境変数を設定する必要がなく、推奨されます。heroku mcp:start コマンドは、Heroku CLI バージョン 10.8.1 以降で利用できます。

heroku mcp:start を使って設定する利点は次のとおりです。

• Heroku API キーを管理したり公開したりする必要がありません
• 現在の Heroku CLI 認証コンテキストを使用します
• 対応クライアントとシームレスに連携します

Claude Desktop の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

Zed の設定例：

{
  "context_servers": {
    "heroku": {
      "command": {
        "path": "heroku",
        "args": ["mcp:start"]
      }
    }
  }
}

Cursor の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

Windsurf の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

Cline の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

VSCode の設定例：

{
  "mcp": {
    "servers": {
      "heroku": {
        "type": "stdio",
        "command": "heroku",
        "args": ["mcp:start"]
      }
    }
  }
}

Trae の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "heroku mcp:start"
    }
  }
}

注： heroku mcp:start を使用すると、サーバーは現在の Heroku CLI セッションを使って認証するため、HEROKU_API_KEY 環境変数を設定する必要はありません。heroku mcp:start の使用を推奨しますが、API キーを使用する場合は、以下の代替設定を利用できます。

npx -y @heroku/mcp-server を使用した Heroku Platform MCP Server の設定

npx -y @heroku/mcp-server コマンドを使用して、Heroku Platform MCP Server を起動することもできます。この方法では、Heroku の認証トークンを使用してHEROKU_API_KEY環境変数を設定する必要があります。

HEROKU_API_KEY の生成

次のいずれかの方法で、Heroku 認証トークンを生成します。

• Heroku CLI コマンドを使用します。

    heroku authorizations:create
  

• CLI で既存のトークンを使用します。

    heroku auth:token
  

  トークンをコピーし、以下の手順で HEROKU_API_KEY として使用します。

• Heroku Dashboard で：

  1. アバターを選択し、Account Settings を選択します。
  2. Applications タブを開きます。
  3. Authorizations の横にある Create authorization をクリックします。

Claude Desktop の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
      }
    }
  }
}

Zed の設定例：

{
  "context_servers": {
    "heroku": {
      "command": {
        "path": "npx",
        "args": ["-y", "@heroku/mcp-server"],
        "env": {
          "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
        }
      }
    }
  }
}

Cursor の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "npx -y @heroku/mcp-server",
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
      }
    }
  }
}

Windsurf の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
      }
    }
  }
}

Cline の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
      }
    }
  }
}

VSCode の設定例：

{
  "mcp": {
    "servers": {
      "heroku": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@heroku/mcp-server"],
        "env": {
          "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
        }
      }
    }
  }
}

Trae の設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>"
      }
    }
  }
}

注： npx -y @heroku/mcp-server を使用する場合は、Heroku 認証トークンを環境変数 HEROKU_API_KEY に設定する必要があります。

利用可能なツール

アプリケーション管理

• list_apps - Heroku アプリをすべて一覧表示します。個人、コラボレーター、チーム、スペースでアプリを絞り込めます。
• get_app_info - 構成、dyno、アドオンなど、アプリの詳細情報を取得します。
• create_app - リージョン、チーム、スペースをカスタマイズして、新しいアプリを作成します。
• rename_app - 既存のアプリの名前を変更します。
• transfer_app - アプリの所有権を別のユーザーまたはチームに移転します。
• deploy_to_heroku - app.json 構成を使用してプロジェクトを Heroku にデプロイします。チームへのデプロイ、プライベートスペース、環境設定に対応しています。
• deploy_one_off_dyno - Heroku のワンオフ dyno 上のサンドボックス環境で、コードやコマンドを実行します。ファイルの作成、ネットワークアクセス、環境変数、自動クリーンアップに対応しています。スクリプト、テスト、一時的なワークロードの実行に最適です。

プロセスと dyno の管理

• ps_list - アプリの dyno をすべて一覧表示します。
• ps_scale - dyno の数を増減したり、サイズを変更したりします。
• ps_restart - 特定の dyno、プロセスタイプ、またはすべての dyno を再起動します。

アドオン

• list_addons - すべてのアプリ、または特定のアプリのアドオンをすべて一覧表示します。
• get_addon_info - 特定のアドオンの詳細情報を取得します。
• create_addon - アプリに新しいアドオンをプロビジョニングします。

メンテナンスとログ

• maintenance_on - アプリのメンテナンスモードを有効にします。
• maintenance_off - アプリのメンテナンスモードを無効にします。
• get_app_logs - アプリケーションのログを表示します。

パイプライン管理

• pipelines_create - 新しいパイプラインを作成します。
• pipelines_promote - パイプライン内の次のステージにアプリを昇格させます。
• pipelines_list - 利用可能なパイプラインを一覧表示します。
• pipelines_info - パイプラインの詳細情報を取得します。

チームとスペースの管理

• list_teams - 所属しているチームを一覧表示します。
• list_private_spaces - 利用可能なスペースを一覧表示します。

PostgreSQL データベース管理

• pg_psql - Heroku PostgreSQL データベースに対して SQL クエリを実行します。
• pg_info - データベースの詳細情報を表示します。
• pg_ps - アクティブなクエリと実行の詳細を表示します。
• pg_locks - データベースのロックを表示し、ブロックしているトランザクションを特定します。
• pg_outliers - リソースを大量に消費するクエリを特定します。
• pg_credentials - データベースの認証情報とアクセスを管理します。
• pg_kill - 特定のデータベースプロセスを終了します。
• pg_maintenance - データベースのメンテナンス情報を表示します。
• pg_backups - データベースのバックアップとスケジュールを管理します。
• pg_upgrade - PostgreSQL を新しいバージョンにアップグレードします。

デバッグ

MCP inspectorまたは VS Code の実行とデバッグ機能を使用して、 サーバーを実行し、デバッグできます。

1. プロジェクトのルートから npm link を実行して、プロジェクトをグローバル CLI としてリンクします。
2. npm run build:dev でビルドするか、npm run build:watch でファイルの変更を監視し、自動的にビルドします。

MCP Inspector を使用する

コードにブレークポイントを設定せずに、MCP inspector を使用します。

# Breakpoints are not available
npx @modelcontextprotocol/inspector heroku-mcp-server

または、特定のディレクトリにパッケージをインストールした場合、もしくは Heroku MCP server を積極的に開発している場合は、次のようにします。

cd /path/to/servers
npx @modelcontextprotocol/inspector dist/index.js

VS Code の実行とデバッグ機能を使用する

コード内のブレークポイントを完全に利用できる 実行とデバッグのランチャーを VS Code で使用します。

1. 実行デバッグを見つけて選択します。
2. ドロップダウンから「MCP Server Launcher」という名前の構成を選択します。
3. 実行／デバッグボタンを選択します。

VS Code／Cursor のデバッグ設定

ブレークポイントを使用したローカルデバッグを設定するには、次の手順を実行します。

1. VS Code のユーザー設定に Heroku 認証トークンを保存します。

   • コマンドパレットを開きます（Cmd/Ctrl + Shift + P）。
   • Preferences: Open User Settings (JSON) と入力します。
   • 次のスニペットを追加します。

   {
     "heroku.mcp.authToken": "your-token-here"
   }
   

2. .vscode/launch.json を作成または更新します。

   {
     "version": "0.2.0",
     "configurations": [
       {
         "type": "node",
         "request": "launch",
         "name": "MCP Server Launcher",
         "skipFiles": ["<node_internals>/**"],
         "program": "${workspaceFolder}/node_modules/@modelcontextprotocol/inspector/bin/cli.js",
         "outFiles": ["${workspaceFolder}/**/dist/**/*.js"],
         "env": {
           "HEROKU_API_KEY": "${config:heroku.mcp.authToken}",
           "DEBUG": "true"
         },
         "args": ["heroku-mcp-server"],
         "sourceMaps": true,
         "console": "integratedTerminal",
         "internalConsoleOptions": "neverOpen",
         "preLaunchTask": "npm: build:watch"
       },
       {
         "type": "node",
         "request": "attach",
         "name": "Attach to Debug Hook Process",
         "port": 9332,
         "skipFiles": ["<node_internals>/**"],
         "sourceMaps": true,
         "outFiles": ["${workspaceFolder}/dist/**/*.js"]
       },
       {
         "type": "node",
         "request": "attach",
         "name": "Attach to REPL Process",
         "port": 9333,
         "skipFiles": ["<node_internals>/**"],
         "sourceMaps": true,
         "outFiles": ["${workspaceFolder}/dist/**/*.js"]
       }
     ],
     "compounds": [
       {
         "name": "Attach to MCP Server",
         "configurations": ["Attach to Debug Hook Process", "Attach to REPL Process"]
       }
     ]
   }
   

3. .vscode/tasks.json を作成します。

   {
     "version": "2.0.0",
     "tasks": [
       {
         "type": "npm",
         "script": "build:watch",
         "group": {
           "kind": "build",
           "isDefault": true
         },
         "problemMatcher": ["$tsc"]
       }
     ]
   }
   

4. （任意）TypeScript ファイルにブレークポイントを設定します。

5. F5 キーを押すか、Run and Debug サイドバーを使用します。

注：デバッガーは起動前に TypeScript ファイルを自動的にビルドします。

環境変数

Heroku Platform MCP Server は、次の環境変数をサポートしています。

HEROKU_API_KEY

Heroku Platform での認証に必要な Heroku 認証トークンです。

MCP_SERVER_REQUEST_TIMEOUT

コマンド実行のタイムアウト時間をミリ秒で指定します。設定されていない場合、デフォルトは 15000（15 秒）です。

タイムアウトをカスタマイズした設定例：

{
  "mcpServers": {
    "heroku": {
      "command": "npx",
      "args": ["-y", "@heroku/mcp-server"],
      "env": {
        "HEROKU_API_KEY": "<YOUR_HEROKU_AUTH_TOKEN>",
        "MCP_SERVER_REQUEST_TIMEOUT": "30000"
      }
    }
  }
}