Bruno MCP server

🔌 Bruno MCP Server for Python

Python MCP server for running Bruno collections. It exposes a Model Context Protocol server over stdio with tools that run collections through the bru CLI and return normalized JSON results.

Note: All examples in this repository use placeholder names (project1, /home/user/project/bruno, example.test). Replace them with your own paths and collection names.

✨ Features

• Run Bruno collections natively using the Bruno CLI.
• Discover collections and sibling environment files automatically.
• Support environment files and dynamic environment variables.
• Secure Secret Injection: Pass secrets to Bruno without exposing values to the LLM via inherited_variables. Secret values are injected through a temporary, owner-only --env-file and the child process environment — they never appear in CLI arguments (ps output) or logs.
• Filter Inspection: Inspect documented query filters and run temporary filter scenarios without modifying the source collection.
• Two-Phase Full Validation: Execute baseline tests + all documented filters in a single tool call.
• Normalized Outputs: Return structured execution results containing success, summary, failures, and timings.

📦 Requirements

• Python: 3.10 or newer
• Package Manager: uv
• Node Package Manager: npm (only if the Bruno CLI is not already installed)

The installer checks whether the Bruno CLI command bru is available. If it is missing, the server fails with an explicit error instead of silently installing packages. To install the pinned version manually:

npm install -g @usebruno/cli@4.2.0

Runtime auto-install is available but opt-in: set BRUNOMCPAUTOINSTALLBRU=1 (or autoinstall = true under [bruno] in the config file) and the server installs exactly the pinned version from cliversion / BRUNOMCPBRU_VERSION.

🚀 Installation & Running

1. Installation

Install dependencies using uv:

uv sync

(If your configured package index does not mirror the MCP Python SDK, point uv at PyPI for the sync: UVDEFAULTINDEX=https://pypi.org/simple uv sync)

2. Running the Server

You can run the server directly using uv:

uv run bruno-mcp

Alternatively, run the module directly inside the uv environment: uv run python -m brunomcp*

⚙️ Configuration

MCP Configuration

Example MCP stdio configuration from this workspace root:

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

Configuration File (bruno-mcp.toml)

Default roots and auth aliases can be configured in bruno-mcp.toml in the current working directory, or globally in ~/.config/bruno-mcp/config.toml.

See bruno-mcp.example.toml for a commented template:

[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"
]

Shortened. The full README is on GitHub.