mcp-bruno

🔌 Python 用 Bruno MCP サーバー

Bruno コレクションを実行する Python 製 MCP サーバーです。stdio 経由で Model Context Protocol サーバーを公開し、bru CLI を使ってコレクションを実行するツールと、標準化された JSON 結果を返します。

注：このリポジトリ内の例では、すべてプレースホルダー名（project1、/home/user/project/bruno、example.test）を使用しています。ご自身のパスとコレクション名に置き換えてください。

✨ 機能

• Bruno コレクションの実行： Bruno CLI を使ってネイティブに実行します。
• コレクションの検出： コレクションと隣接する環境ファイルを自動的に検出します。
• 環境ファイルのサポート： 環境ファイルと動的な環境変数をサポートします。
• 安全なシークレット注入： inherited_variables を使うことで、値を LLM に公開せずに Bruno にシークレットを渡せます。シークレット値は一時的な所有者専用の --env-file と子プロセスの環境変数を通じて注入され、CLI 引数（ps の出力）やログには決して表示されません。
• フィルターの検査： ドキュメント化されたクエリフィルターを検査し、ソースコレクションを変更せずに一時的なフィルターシナリオを実行します。
• 2 段階の完全な検証： ベースラインテストと、ドキュメント化されたすべてのフィルターを 1 回のツール呼び出しで実行します。
• 標準化された出力： success、summary、failures、timings を含む構造化された実行結果を返します。

📦 要件

• Python： 3.10 以降
• パッケージマネージャー： uv
• Node パッケージマネージャー： npm (Bruno CLI がまだインストールされていない場合のみ)

インストーラーは、Bruno CLI コマンド bru が利用可能かどうかを確認します。利用できない場合、パッケージを暗黙にインストールするのではなく、明示的なエラーを返してサーバーを停止します。固定バージョンを手動でインストールするには、次のコマンドを実行します。

npm install -g @usebruno/[email protected]

実行時の自動インストールも利用できますが、初期状態では無効です。有効にするには、BRUNO_MCP_AUTO_INSTALL_BRU=1 を設定するか、設定ファイルの [bruno] 内で auto_install = true を設定します。有効にすると、サーバーは cli_version / BRUNO_MCP_BRU_VERSION で指定された固定バージョンをインストールします。

🚀 インストールと実行

1. インストール

uv を使って依存関係をインストールします。

uv sync

(設定したパッケージインデックスが MCP Python SDK をミラーしていない場合は、同期時に uv が PyPI を参照するように設定します：UV_DEFAULT_INDEX=https://pypi.org/simple uv sync)

2. サーバーの実行

uv を使ってサーバーを直接実行できます。

uv run bruno-mcp

または、uv 環境内でモジュールを直接実行します：uv run python -m bruno_mcp

⚙️ 設定

MCP の設定

このワークスペースのルートから使用する MCP stdio 設定の例：

{
  "mcpServers": {
    "bruno-runner": {
      "command": "uv",
      "args": ["run", "bruno-mcp"]
    }
  }
}

設定ファイル（bruno-mcp.toml）

既定のルートと認証エイリアスは、現在の作業ディレクトリにある bruno-mcp.toml、またはグローバル設定ファイル ~/.config/bruno-mcp/config.toml で設定できます。

コメント付きのテンプレートについては、bruno-mcp.example.toml を参照してください。

[workspace]
roots = [
  "/home/user/project/bruno"
]

[bruno]
cli_version = "4.2.0"   # pinned Bruno CLI version
auto_install = false     # never install bru silently at runtime

[limits]
run_timeout_seconds = 300
max_output_bytes = 8388608
max_concurrent_runs = 2

[artifacts]
ttl_hours = 24           # raw reports are auto-deleted after this
max_files = 50

[security]
enforce_root_confinement = true   # reject collection paths outside workspace roots

[auth]
inherited_variables = [
  "BRUNO_AUTH_TOKEN",
  "BRUNO_API_KEY"
]

[defaults]
environment = "dev"

すべての設定は環境変数（BRUNO_MCP_BRU_VERSION、BRUNO_MCP_AUTO_INSTALL_BRU、BRUNO_MCP_RUN_TIMEOUT、BRUNO_MCP_MAX_OUTPUT_BYTES、BRUNO_MCP_MAX_CONCURRENT_RUNS、BRUNO_MCP_ARTIFACTS_DIR、BRUNO_MCP_ARTIFACT_TTL_HOURS、BRUNO_MCP_ARTIFACT_MAX_FILES、BRUNO_MCP_ENFORCE_ROOT_CONFINEMENT、BRUNO_MCP_LOG_LEVEL）でも設定できます。環境変数の設定はファイルの設定より優先されます。

注： インストーラーは、ダミーのルートを含む ~/.config/bruno-mcp/config.toml を作成します。ローカルの bruno-mcp.toml ファイルは Git で無視されるため、実際のパスや環境名がコミットされることはありません。

💻 VS Code へのローカルインストール

プロジェクトのルートから、uv を使って依存関係をインストールします。

UV_DEFAULT_INDEX=[https://pypi.org/simple](https://pypi.org/simple) uv sync

Bruno CLI が利用可能であることを確認します（bru --version）。このリポジトリには .vscode/mcp.json が含まれており、VS Code がワークスペースからローカル MCP サーバーを検出できます。

{
  "servers": {
    "bruno-runner": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "bruno-mcp"]
    }
  }
}

依存関係の同期後、VS Code のウィンドウを再読み込みします。MCP サーバーの一覧に bruno-runner サーバーが表示されます。

グローバルインストール

VS Code のユーザープロファイルに MCP サーバーをインストールし、すべてのワークスペースから利用できるようにするには、次のコマンドを実行します。

uv run python scripts/install_vscode.py

(再利用可能な Copilot プロンプトとエージェントもグローバルにインストールするには、上記のコマンドに --with-copilot-customizations を追加します。)

別のローカル VS Code ワークスペースに手動でインストールするには、コマンドの引数に --directory を含めます。

"args": ["--directory", "/home/user/mcp-bruno", "run", "bruno-mcp"]

🧰 利用可能なツール

🔍 list-collections

ルートディレクトリまたは設定済みのルート以下にある Bruno コレクションを一覧表示します。ユーザーがフルパスではなく、コレクション名の一部を指定した場合に使用します。

• root (省略可能)：Bruno のルートディレクトリ（通常は collections/ と environments/ を含みます）。
• query (省略可能)：コレクション名とパスの絞り込みに使う、大文字と小文字を区別しないテキストです。

▶️ run-collection

Bruno コレクションを実行し、正規化された実行結果を返します。

• collection (必須)：Bruno コレクションへのパスです。
• environment (省略可能)：環境ファイルへのパスです。
• variables (省略可能)：KEY=value 形式の環境変数です。
• inherited_variables (省略可能)：MCP サーバープロセスから読み取り、値を LLM に公開せずに Bruno に渡す環境変数名です。値は一時的な所有者のみがアクセスできる --env-file と子プロセスの環境変数を介して渡されます（{{process.env.NAME}} も使用できます）。CLI 引数には渡されません。

{
  "collection": "/home/user/project/bruno/collections/project1",
  "environment": "dev",
  "inherited_variables": ["BRUNO_AUTH_TOKEN"]
}

🌍 discover-environments

Bruno コレクション周辺のフォルダー構造を調べ、同階層にある環境ディレクトリ、利用可能な環境名、変数名を返します（シークレットの値は返しません）。

📖 read-result-artifact

run-collection が返す生の Bruno JSON アーティファクトのパスから、範囲を限定して秘匿情報を削除した概要を読み取ります。

• path (必須): 前回の実行で返された artifact.path の値です。
• max_items (任意): リクエストごとにサンプリングするレスポンス項目数です（デフォルトは 3、最大 20）。

🧪 list-request-filters と run-filter-scenarios

• list-request-filters: YAML リクエストファイルを調べ、クエリパラメーターを有効なグループと無効なグループに分けて返します。
• run-filter-scenarios: ソースファイルを変更せず、選択した無効なクエリパラメーターを有効にした一時的なリクエストのバリエーションを実行します。

🛡️ run-full-validation

1 回のツール呼び出しで、2 段階のオーケストレーションを実行します。

1. ベースライン: コレクションを 1 回実行し、すべてのエンドポイントがエラーなく応答すること（4xx／5xx がないこと）を確認します。
2. フィルター: ベースラインが成功した場合にのみ実行します。すべてのエンドポイントで、無効なクエリフィルターを自動検出してテストします。

エージェントスキルと Copilot 連携

これらのワークフローでは、bruno-runner として設定された MCP サーバーを使用します。スキルやプロンプトをインストールしても、サーバーはインストールも設定もされません。まず、上記の MCP 設定を使ってクライアントでサーバーを設定してください。

VS Code GitHub Copilot

リポジトリには、カスタムエージェントとスラッシュコマンドのプロンプトが含まれています。このリポジトリのルートから、対象のワークスペースにコピーします。

mkdir -p /path/to/workspace/.github/agents /path/to/workspace/.github/prompts
cp copilot/agents/bruno-runner.agent.md /path/to/workspace/.github/agents/
cp copilot/prompts/run-bruno-collection.prompt.md /path/to/workspace/.github/prompts/

Copilot Chat のエージェント選択メニューで bruno-runner カスタムエージェントを選択するか（対応している場合は @bruno-runner）、Chat で /run-bruno-collection <collection or path> [environment] を実行します。スラッシュコマンドは、カスタムエージェントを選択しなくても動作します。

または、次のコマンドで両方をグローバルにインストールできます。

uv run python scripts/install_vscode.py --with-copilot-customizations

Claude Code / Cursor / Windsurf

汎用の Bruno Runner スキルには、コレクションの検出、環境の選択、標準的な実行、対象を絞ったフィルターシナリオ、2 段階の完全検証、シークレットの安全な取り扱い、レポートのルールがまとめられています。

Claude Code の場合は、対象プロジェクトのスキルディレクトリにコピーします。

mkdir -p /path/to/workspace/.claude/skills/bruno-runner
cp skills/bruno-runner/SKILL.md /path/to/workspace/.claude/skills/bruno-runner/SKILL.md

または、絶対パスで指定したソースパスを使って、スキルディレクトリへのシンボリックリンクを作成します。

mkdir -p /path/to/workspace/.claude/skills
ln -s /absolute/path/to/mcp-bruno/skills/bruno-runner /path/to/workspace/.claude/skills/bruno-runner

Cursor の場合は、同じディレクトリを .cursor/skills/bruno-runner/ にコピーするか、シンボリックリンクを作成します。Windsurf の場合は、対象ワークスペースの .windsurf/skills/bruno-runner/ を使用します。スキルの検出方法は、クライアントのバージョンと設定によって異なります。代わりにルールを使用するクライアントでは、スキルの本文をそのクライアント固有のルール形式に適合させてください（たとえば、Cursor のルール用フロントマターを含む .cursor/rules/bruno-runner.mdc ファイル）。SKILL.md をルールディレクトリにコピーするだけでは、有効化される保証はありません。

コレクションの実行、特定のフィルターの検証、またはすべてのエンドポイントとフィルターのテストを依頼できます。ワークフローは inherited_variables を使ってローカルでシークレットを解決します。認証情報をチャットに貼り付けないでください。サーバーのローカルトークンのフォールバック先は ~/.config/bruno-mcp/.bearer_token（生のトークン）であり、~/.config/mcp-bruno/.bearer_token ではありません。更新後は、MCP サーバーを再起動してください。

リポジトリのアセット

スキルと Copilot のテンプレートは、pyproject.toml で検出される src/ 内の Python パッケージとは別に、リポジトリルートの skills/ と copilot/ に整理されています。これらはリポジトリのアセットであり、インストールされる wheel リソースではありません。上記のコピー、シンボリックリンク、インストーラーの各コマンドを使うには、リポジトリをチェックアウトしてください。Python パッケージをインストールしただけでは、クライアントにエージェントワークフローは登録されません。

実行結果は、サーバーの正規化された出力形式を維持します。

{
  "success": true,
  "summary": {
    "total": 5,
    "failed": 0,
    "passed": 5
  },
  "failures": [],
  "auth_failure": false,
  "auth_message": null,
  "timings": {
    "started": "2024-03-14T10:00:00.000000Z",
    "completed": "2024-03-14T10:00:01.000000Z",
    "duration": 1000
  }
}

🐳 Docker

Docker イメージには、この Python サーバーと Bruno CLI の両方がインストールされます。

docker build -t bruno-mcp-python .
docker run --rm -i bruno-mcp-python

🛠️ 開発とプロジェクト構成

コマンド:

• ソースをコンパイルチェックします: uv run python -m compileall src
• テストスイートを実行します: uv run python -m unittest discover -s tests -v

構成:

.
├── src/bruno_mcp/         # MCP server, runner, config, and types
├── scripts/               # VS Code installer script
├── copilot/               # Reusable Copilot prompt and agent templates
├── skills/bruno-runner/    # Universal Agent Skill (SKILL.md)
├── tests/                 # Unit tests
├── .vscode/mcp.json       # Workspace MCP server entry
└── bruno-mcp.example.toml # Commented configuration template

mcp-name: io.github.kta41/mcp-bruno

📄 ライセンス

MIT ライセンスの下で公開されています。