Heroku Code MCP

Heroku Code MCP

Code Mode パターン（search + execute + auth_status）を採用した、Heroku Platform API 用のコンパクトな MCP サーバーです。

Heroku Code MCP は、エージェントクライアント向けに、Heroku の操作を行うための小規模でトークン効率の高い操作インターフェースを提供します。ライブ API ツールと併せてワークフローのガイダンス、安全性の確認、Heroku 製品に関するコンテキストも必要な場合は、Heroku Skills と組み合わせてください。

設計の参考資料：

• Cloudflare Code Mode MCP
• Anthropic：効果的なエージェントの構築

クイックスタート

デフォルトの MCP URL：http://127.0.0.1:3000/mcp

git clone https://github.com/dsouzaAnush/heroku-code-mcp.git
cd heroku-code-mcp
npm install
npm run build
npm test

Heroku CLI から認証情報を設定します：

heroku auth:whoami
npm run seed:token

サーバーを起動します：

TOKEN_STORE_PATH=./data/tokens.integration.json \
TOKEN_ENCRYPTION_KEY_BASE64="<seed-output-key>" \
PORT=3000 HOST=127.0.0.1 npm run dev

動作を簡易テストします：

curl -sS http://127.0.0.1:3000/healthz
MCP_URL=http://127.0.0.1:3000/mcp USER_ID=default npm run smoke:mcp

npm で公開する前でも、GitHub からパッケージを実行できます：

HOST=127.0.0.1 PORT=3333 \
TOKEN_STORE_PATH="$HOME/.heroku-code-mcp/tokens.json" \
TOKEN_ENCRYPTION_KEY_BASE64="<base64-32-byte-key>" \
WRITE_CONFIRMATION_SECRET="<random-secret>" \
npx -y github:dsouzaAnush/heroku-code-mcp

エージェントクライアントへのインストール

Claude Code

スキルと MCP 接続を利用するには、コンパニオンプラグインをインストールします：

claude plugin marketplace add dsouzaAnush/heroku-plugin
claude plugin install heroku@heroku-plugin
claude plugin enable heroku@heroku-plugin

または、実行中の MCP サーバーを直接追加します：

claude mcp add \
  --transport http \
  --scope local \
  heroku-code-mcp \
  http://127.0.0.1:3000/mcp \
  --header "x-user-id: default"

Claude Desktop

対応している場合は、HTTP エンドポイントを直接使用します：

{
  "mcpServers": {
    "heroku-code-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}

stdio サーバーが必要な Desktop ビルドでは、mcp-remote を介して接続します：

{
  "mcpServers": {
    "heroku-code-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3000/mcp", "--allow-http", "--header", "x-user-id:default"]
    }
  }
}

次のコマンドで .mcpb バンドルをビルドします：

npm run build:mcpb

Codex

Codex では、スキルと任意の MCP 接続に Heroku Plugin を使用します：

codex plugin marketplace add dsouzaAnush/heroku-plugin --ref main

Codex の Plugins タブで heroku-plugin@heroku-plugin を有効にするか、次を追加します：

[plugins."heroku-plugin@heroku-plugin"]
enabled = true

プラグイン経由でライブ Heroku API ツールを使用する場合は、この MCP サーバーを http://127.0.0.1:3333/mcp で実行します。

Cursor

git clone https://github.com/dsouzaAnush/heroku-plugin.git
cursor agent --plugin-dir heroku-plugin

MCP サーバーを ~/.cursor/mcp.json またはプロジェクトローカルの .cursor/mcp.json に追加します：

{
  "mcpServers": {
    "heroku-code-mcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3333/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}

その他の MCP クライアント

ストリーミング可能な HTTP を使用します：

{
  "mcpServers": {
    "heroku-code-mcp": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "x-user-id": "default"
      }
    }
  }
}

または、stdio にブリッジします：

{
  "mcpServers": {
    "heroku-code-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3000/mcp", "--allow-http", "--header", "x-user-id:default"]
    }
  }
}

仕組み

ツール	機能	目的
auth_status	呼び出し元が Heroku で認証されているかを報告します	API 操作の前にエージェントが適切に処理を分岐できるようにします
search	スキーマとドキュメントのコンテキストを基に Heroku の操作をランク付けします	エンドポイント形式の多数のツールを最初から公開せずに済みます
execute	パラメーターと本文を検証し、選択された Heroku の操作を呼び出します	決定論的な実行経路をひとつ提供します

一般的な流れ：

1. auth_status を呼び出します。
2. 自然言語の意図を指定して search を呼び出します。
3. ひとつの operation_id を選択します。
4. path_params、query_params、body を指定して execute を呼び出します。
5. 書き込み操作では、dry_run=true を実行してから、返された confirm_write_token と ALLOW_WRITES=true を指定して再実行します。

例：

{
  "query": "list apps",
  "limit": 5
}

{
  "operation_id": "GET /apps"
}

{
  "operation_id": "PATCH /apps/{app_identity}",
  "path_params": {
    "app_identity": "my-app"
  },
  "body": {
    "maintenance": true
  },
  "dry_run": true
}

安全性と設定

変更操作（POST、PATCH、PUT、DELETE）はデフォルトでブロックされます。書き込みを許可するには、ALLOW_WRITES=true を設定してドライランをリクエストし、返された confirm_write_token を指定して再実行します。機密性の高いヘッダーと本文のフィールドはマスキングされます。

主な環境変数：

• ALLOW_WRITES
• REQUEST_TIMEOUT_MS
• MAX_RETRIES
• CATALOG_CACHE_PATH
• READ_CACHE_TTL_MS
• EXECUTE_MAX_BODY_BYTES
• EXECUTE_BODY_PREVIEW_CHARS

完全な例：.env.example

ベンチマーク

ベンチマークは2026年2月22日に、両方の実装で同じマシンとアカウントを使用して測定しました。

指標	heroku-code-mcp	公式 Heroku MCP	差
ツール数	3	37	91.9% 少ない
ツール一覧のペイロードサイズ（バイト）	1,469	25,500	94.2% 少ない
ツール一覧の概算トークン数	368	6,375	94.2% 少ない
接続時間の平均	14.8 ms	10,168.7 ms	687 倍高速
list_tools の平均時間	4.3 ms	10.3 ms	2.4 倍高速
読み取り操作の平均時間	528.0 ms（execute GET /apps）	9,697.4 ms（list_apps）	18.4 倍高速

グラフ：

• 
• 

詳細な方法と成果物は、BENCHMARKS.md と benchmarks/results/ にあります。

開発とリリース

ローカルで検証します：

npm run build
npm test
npm run validate:server
npm run publish:dry-run

このリポジトリでは、無料の GitHub Actions を使用しています：

• validate.yml は、PR と main へのプッシュ時にビルド、テスト、server.json の検証、npm pack のドライランを実行します。
• release.yml は v* タグで実行され、.mcpb をビルドし、リリース用の server.json を更新して、GitHub Release を作成または更新し、GitHub OIDC を通じて MCP Registry に公開します。
• Dependabot は npm と GitHub Actions の依存関係を毎週チェックします。

必要に応じて手動で公開します：

npm publish --access public
mcp-publisher login github
mcp-publisher publish server.json

CI ベースで npm に公開するには、リポジトリ dsouzaAnush/heroku-code-mcp とワークフロー release.yml の npm Trusted Publishing を設定し、publish_npm=true を指定してリリースワークフローを実行します。

リポジトリ構成

• src/schema/*：取り込み、操作の正規化、キャッシュ
• src/search/*：検索インデックスとランキング
• src/execute/*：検証と Heroku API の実行
• src/auth/*：OAuth と暗号化されたトークンの保存
• tests/*：カタログ、検索、実行のテスト
• benchmarks/results/*：ベンチマークの成果物
• server.json：MCP Registry のメタデータ

ブランドとトラブルシューティング

このリポジトリには、assets に公式の Heroku ワードマークとマークが含まれています。Heroku ブランドガイドラインに従って使用してください。

よくある問題の解決方法：

• MCP Inspector の接続エラー：URL http://127.0.0.1:3000/mcp とサーバーの状態を確認してください。
• AUTH_REQUIRED：トークンを登録するか、OAuth を完了してください。
• 書き込みがブロックされる：ALLOW_WRITES=true を確認し、ドライランの確認トークンを送信してください。
• レスポンス本文が大きい：クエリの範囲を絞るか、出力上限を下げてください。