mcp-bruno
Enables running Bruno API collections through the Bruno CLI, including listing collections, discovering environments, passing environment variables and inherited secrets, inspecting query filters, running filter scenarios, and performing baseline/full validation with normalized execution results.
๐ Bruno MCP Server for Python
Python MCP server for running Bruno collections. It exposes a Model Context Protocol server over
stdiowith tools that run collections through thebruCLI 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-fileand the child process environment โ they never appear in CLI arguments (psoutput) 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, andtimings.
Related MCP server: Bruno MCP Server
๐ฆ Requirements
Python: 3.10 or newer
Package Manager:
uvNode 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.0Runtime auto-install is available but opt-in: set BRUNO_MCP_AUTO_INSTALL_BRU=1 (or auto_install = true under [bruno] in the config file) and the server installs exactly the pinned version from cli_version / BRUNO_MCP_BRU_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: UV_DEFAULT_INDEX=https://pypi.org/simple uv sync)
2. Running the Server
You can run the server directly using uv:
uv run bruno-mcpAlternatively, run the module directly inside the uv environment: uv run python -m bruno_mcp
โ๏ธ 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"
]
[defaults]
environment = "dev"Every setting can also be set via environment variables (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), which take precedence over the file.
Note: The installer creates
~/.config/bruno-mcp/config.tomlwith a dummy root. Localbruno-mcp.tomlfiles are git-ignored so real paths and environment names are never committed.
๐ป Local VS Code Installation
From the project root, install dependencies with uv:
UV_DEFAULT_INDEX=[https://pypi.org/simple](https://pypi.org/simple) uv syncEnsure the Bruno CLI is available (bru --version). This repository includes .vscode/mcp.json, allowing VS Code to discover the local MCP server from the workspace:
{
"servers": {
"bruno-runner": {
"type": "stdio",
"command": "uv",
"args": ["run", "bruno-mcp"]
}
}
}Reload the VS Code window after syncing dependencies. The bruno-runner server should now be available in the MCP servers list.
Global Installation
To install the MCP server in the VS Code user profile so it is available from any workspace:
uv run python scripts/install_vscode.py(To also install the reusable Copilot prompt and agent globally, append --with-copilot-customizations to the command above).
To install it manually in another local VS Code workspace, change the command args to include --directory:
"args": ["--directory", "/home/user/mcp-bruno", "run", "bruno-mcp"]๐งฐ Available Tools
๐ list-collections
Lists Bruno collections below a root directory or configured roots. Use it when the user provides a partial collection name instead of a full path.
root(optional): Bruno root directory (usually containscollections/andenvironments/).query(optional): Case-insensitive text used to filter collection names and paths.
โถ๏ธ run-collection
Runs a Bruno collection and returns normalized execution results.
collection(required): Path to the Bruno collection.environment(optional): Path to an environment file.variables(optional): Environment variables asKEY=valuestrings.inherited_variables(optional): Names of environment variables to read from the MCP server process and inject into Bruno without exposing values to the LLM. Values travel via a temporary owner-only--env-fileand the child process environment ({{process.env.NAME}}also works) โ never in CLI arguments.
Auth Handling:
For secrets, prefer inherited_variables instead of writing values in chat. By default, the secure MCP input BRUNO_AUTH_TOKEN can satisfy Bruno variables named bearerToken, BEARER_TOKEN, AUTH_TOKEN, TOKEN, accessToken, or access_token. Secrets are injected via a temporary private --env-file; if the selected --env environment file declares the same variable (which would take precedence inside bru), the run transparently switches to a temporary sanitized copy of the collection with the conflicting entry removed, so the injected secret always wins and source files are never modified.
Workspace confinement:
When [workspace] roots are configured (and at least one exists on disk), collection paths outside those roots are rejected with a clear error. Set enforce_root_confinement = false to disable.
Execution limits:
Each bru run has a configurable timeout (run_timeout_seconds, default 300s), bounded stdout/stderr capture (max_output_bytes), and a concurrency cap (max_concurrent_runs). Raw JSON reports are stored as artifacts with owner-only (0600) permissions and expire automatically (ttl_hours / max_files). Structured logs go to stderr (BRUNO_MCP_LOG_LEVEL).
Supported Collection Inputs:
Collection directory:
/path/to/bruno/collections/project1Bruno request file:
/path/to/bruno/collections/project1/request.bruInternal
.vrurequest file:/path/to/bruno/collections/project1/request.vruOpen collection descriptor:
/path/to/bruno/collections/project1/opencollection.yml
When Bruno failures look like authentication problems, the response includes auth_failure: true and an auth_message.
Example with inherited secrets:
{
"collection": "/home/user/project/bruno/collections/project1",
"environment": "dev",
"inherited_variables": ["BRUNO_AUTH_TOKEN"]
}๐ discover-environments
Inspects the folder structure around a Bruno collection and returns the sibling environments directory, available environment names, and variable names (without returning secret values).
๐ read-result-artifact
Reads a bounded, redacted summary from the raw Bruno JSON artifact path returned by run-collection.
path(required): Theartifact.pathvalue returned by a previous run.max_items(optional): Number of response items to sample per request (default 3, max 20).
๐งช list-request-filters & run-filter-scenarios
list-request-filters: Inspects YAML request files and returns query params split into enabled and disabled groups.run-filter-scenarios: Runs temporary request variants with selected disabled query params enabled without modifying the source files.
๐ก๏ธ run-full-validation
Two-phase orchestration in a single tool call:
Baseline: Runs the collection once and checks every endpoint responds without errors (no
4xx/5xx).Filters: Only runs if the baseline is green. Automatically discovers and tests every disabled query filter across every endpoint.
Agent Skills & Copilot Integration
These workflows use the MCP server configured as bruno-runner; installing a skill or prompt does not install or configure the server. Configure the server in your client first using the MCP configuration above.
VS Code GitHub Copilot
The repository includes a custom agent and a slash-command prompt. From this repository root, copy them into the target workspace:
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/Select the bruno-runner custom agent in Copilot Chat's agent picker (@bruno-runner where supported), or run /run-bruno-collection <collection or path> [environment] in Chat. The slash command works independently of selecting the custom agent.
Alternatively, install both globally with:
uv run python scripts/install_vscode.py --with-copilot-customizationsClaude Code / Cursor / Windsurf
The universal Bruno Runner skill consolidates collection discovery, environment selection, standard runs, targeted filter scenarios, full two-phase validation, secret safety, and reporting rules.
For Claude Code, copy it into the target project's skill directory:
mkdir -p /path/to/workspace/.claude/skills/bruno-runner
cp skills/bruno-runner/SKILL.md /path/to/workspace/.claude/skills/bruno-runner/SKILL.mdOr symlink the skill directory using an absolute source path:
mkdir -p /path/to/workspace/.claude/skills
ln -s /absolute/path/to/mcp-bruno/skills/bruno-runner /path/to/workspace/.claude/skills/bruno-runnerFor Cursor, copy or symlink the same directory to .cursor/skills/bruno-runner/; for Windsurf, use .windsurf/skills/bruno-runner/ in the target workspace. Skill discovery depends on your client's version and configuration. For clients using rules instead, adapt the skill body into their native rule format (for example, a .cursor/rules/bruno-runner.mdc file with Cursor rule frontmatter); merely copying SKILL.md into a rules directory does not guarantee activation.
Ask to run a collection, validate a specific filter, or test all endpoints and filters. The workflows resolve secrets locally through inherited_variables; never paste credentials into chat. The server's local token fallback is ~/.config/bruno-mcp/.bearer_token (raw token), not ~/.config/mcp-bruno/.bearer_token. After updating it, restart the MCP server.
Repository Assets
Skills and Copilot templates remain organized under skills/ and copilot/ at the repository root, separately from the Python packages discovered under src/ in pyproject.toml. They are repository assets, not installed wheel resources; use a repository checkout for the copy, symlink, and installer commands above. Installing the Python package alone does not register agent workflows with a client.
Execution results retain the server's normalized output contract:
{
"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
The Docker image installs both this Python server and the Bruno CLI:
docker build -t bruno-mcp-python .
docker run --rm -i bruno-mcp-python๐ ๏ธ Development & Project Structure
Commands:
Compile-check the sources:
uv run python -m compileall srcRun the test suite:
uv run python -m unittest discover -s tests -v
Structure:
.
โโโ 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 templatemcp-name: io.github.kta41/mcp-bruno
๐ License
Released under the MIT License.
Available Tools
7 toolsdiscover-environmentsDiscover Bruno environmentsB
Inspect the folder structure around a Bruno collection and return the sibling environments directory, available environment names, and variable names. Secret values are not returned.
Inputs: collection (required).
list-collectionsList Bruno collectionsA
List Bruno collections below a root directory or configured roots. Use this when the user gives a partial collection name instead of a full path.
Inputs: root, query.
list-request-filtersList Bruno request filtersA
Inspect OpenCollection YAML requests and return enabled and disabled query params that can be used as filter scenarios. Secret values are not returned.
Inputs: collection (required).
read-result-artifactRead Bruno result artifactA
Read a bounded, redacted summary from a raw Bruno JSON artifact path returned by run-collection or run-filter-scenarios. Use this when response data is too large to include directly in a tool result.
Inputs: path (required), max_items.
run-collectionRun Bruno collectionA
Run a Bruno collection with the local bru CLI and return normalized JSON with success, request summary, per-request details, failures, and execution timings. Provide collection as the collection path; optionally pass environment and non-secret variables as KEY=value strings. For secrets, pass only names through inherited_variables; values are read from the MCP server process and injected via a temporary private --env-file, never via CLI arguments. Collection paths must stay inside the configured workspace roots.
Inputs: collection (required), variables, environment, inherited_variables.
run-filter-scenariosRun Bruno filter scenariosA
Run temporary Bruno request variants with selected disabled query params enabled, then validate HTTP status and response payload consistency. Each request is also run once without filters (baseline) to distinguish an ignored filter (response identical to baseline) from a filter that legitimately returns zero matches. Infrastructure failures (auth, routing, timeout, connectivity) are reported as inconclusive, never as filter defects. Source collection files are not modified.
Inputs: collection (required), scenarios, variables, environment, +2 more.
run-full-validationRun full Bruno validation (endpoints then filters)A
Two-phase validation. Phase 1 runs the collection once and checks every endpoint is reachable (HTTP status, no request errors). Phase 2 only runs if phase 1 passes: it tests every documented disabled query filter across every endpoint in temporary request copies, without modifying source files. Each scenario is compared against an unfiltered baseline to distinguish ignored filters from legitimate zero-match results, and infrastructure failures are marked inconclusive instead of failed. Returns a consolidated result stating which phase ran, per-endpoint baseline status, and per-endpoint per-filter pass/fail/skip with the reason.
Inputs: collection (required), variables, environment, max_scenarios, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 7 tools
Tools have distinct primary purposes (listing, running, discovering, reading, validating). However, run-filter-scenarios and run-full-validation overlap in testing disabled query filters, requiring careful reading to choose between targeted filter testing and comprehensive two-phase validation.
All tool names follow a consistent lowercase hyphen-separated verb_noun pattern (list-, run-, discover-, read-), with no mixed casing or verb styles.
Seven tools is well-scoped for a Bruno collection runner/validator; each tool covers a distinct stage (discovery, execution, filtering, validation, artifact reading) without bloat.
The surface covers discovery, execution, filter validation, and artifact reading, which are the core lifecycle for running and validating collections. Minor gaps exist (e.g., no dedicated single-request execution or collection editing), but agents can work around them via run-collection and filter scenarios.
Maintenance
Related MCP Connectors
A simple MCP server built with FastMCP and python
The official MCP Server for the Mux API
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Related MCP Servers
- MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) server that enables programmatic creation and management of Bruno API testing collections, environments, and requests through standardized MCP tools.135MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that executes requests from Bruno API collections via the Bruno CLI tool, enabling API request execution and collection management.4MIT
- AlicenseAqualityDmaintenanceRead-only MCP server for indexing and searching Bruno API collections. Enables endpoint discovery and contract retrieval without executing requests.825 npmMIT