MCP Bruno

What mcp-bruno does

The mcp-bruno MCP server exposes Bruno collection operations to MCP-compatible clients through Python. It uses the bru command-line interface to execute collections and converts execution data into structured results with success status, summaries, failures, and timing information.

The project belongs in the 💻 Developer Tools category and is intended for repositories that store Bruno collections, request files, environments, and related artifacts. Collection inputs can be a collection directory, a .bru request file, an internal .vru request file, or an opencollection.yml descriptor.

How it works

The mcp-bruno MCP server communicates over MCP stdio. A client starts it with uv run bruno-mcp, and the server launches Bruno CLI processes for collection runs. Workspace roots can restrict which collection paths are accepted. Execution also supports configurable timeouts, output limits, and a maximum number of concurrent runs.

Environment files can be selected for a run, and variables can be supplied as KEY=value strings. Sensitive values can instead be named in inherited_variables; the server reads those values from its own process environment and passes them through a temporary owner-only environment file and child-process environment. This avoids placing secret values in CLI arguments or returning them to the model.

Raw JSON reports are stored as temporary artifacts with restricted permissions and automatic cleanup. The server can identify likely authentication failures and include an authentication message in the response.

Setup and configuration

Python 3.10 or newer and uv are required. Install the project dependencies with uv sync, then start the server with uv run bruno-mcp or uv run python -m bruno_mcp. The Bruno CLI must be available as bru; the documented pinned version is 4.2.0. Automatic installation is optional and can be enabled with BRUNO_MCP_AUTO_INSTALL_BRU=1 or the matching TOML setting.

Configuration can be stored in bruno-mcp.toml in the working directory or in ~/.config/bruno-mcp/config.toml. Settings cover workspace roots, the Bruno CLI version, automatic installation, run limits, artifact retention, root confinement, inherited variable names, and a default environment. Environment variables override file settings.

A client can register the server with a stdio command using uv and the run bruno-mcp arguments. The repository also documents local and global VS Code setup through an MCP configuration file.

Tools and capabilities

The mcp-bruno MCP server provides tools for:

• Listing collections below a configured or supplied root, with optional case-insensitive name and path filtering.
• Running collections with an environment file, regular variables, or inherited secrets.
• Discovering sibling Bruno environments and their variable names without exposing secret values.
• Reading bounded, redacted result artifacts.
• Inspecting documented query filters and running temporary filter scenarios without changing the source collection.
• Performing baseline tests and documented filter checks through two-phase full validation.

Limitations and notes

The server depends on the Bruno CLI and does not silently install it unless runtime installation is explicitly enabled. Paths outside configured workspace roots are rejected when root confinement is active. Runs are bounded by configured timeout, output-size, and concurrency limits, while stored artifacts are subject to retention limits.

The examples use placeholder paths and collection names; deployments must replace them with local values. Environment variable names are exposed for discovery, but secret values are not returned. A configured environment file can conflict with an injected secret, in which case the server uses a temporary sanitized collection copy so source files remain unchanged.