Bruno MCP

A local MCP v2 stdio server for enumerating and safely editing Bruno workspaces, legacy .bru collections, and OpenCollection YAML collections. It stores MCP-managed secret values in the operating-system keychain and delegates execution to the official bru CLI.

Prerequisites

• Node.js 20 or newer

• npm

• Bruno CLI for run_* tools (bru 4.0.0 is the validated version)

• A native OS credential store for secret tools:

  • macOS Keychain

  • Windows Credential Manager

  • a supported Linux Secret Service

Bruno Desktop is optional. Generated legacy .bru files use the conservative format associated with Desktop 3.4.2, while execution is mechanically validated with CLI 4.0.0. Desktop exposes no supported headless parser, so its compatibility cannot be fully automated without opening the GUI or modifying a real workspace. These versions do not share a major version: keep backups, use revisions, and do not assume a CLI-4-only feature is understood by Desktop 3.4.2. OpenCollection YAML is validated against CLI 4.0.0; Desktop 3.4.2 compatibility is not guaranteed. Desktop refresh behavior is controlled by Bruno, not this server.

Related MCP server: Obsidian MCP Server

Install, build, test, and start

From a source checkout:

npm install
npm run typecheck
npm run build
npm test
npm start

Run the disposable compatibility test when Bruno CLI 4.0.0 is installed:

BRUNO_CLI_PATH=/opt/homebrew/bin/bru npm run test:compat

The smoke test uses only a generated collection under .test-work, an in-memory secret store, and a loopback HTTP server. It never reads or changes the user's Bruno workspace or collections.

After packaging/installing, the executable is:

bruno-mcp

The server uses stdio. Standard output is reserved for MCP protocol messages; diagnostics go to standard error.

Configuration

The legacy aliases BRUNO_MCP_MAX_OUTPUT_BYTES and BRUNO_MCP_MAX_REPORT_BYTES are also accepted. Path lists use : on macOS/Linux and ; on Windows.

MCP client configuration

Build first, then point the client at the built entry point:

{
  "mcpServers": {
    "bruno": {
      "command": "node",
      "args": ["/absolute/path/to/bruno-mcp/dist/index.js"],
      "env": {
        "BRUNO_MCP_WORKSPACE_PATHS": "/Users/me/Library/Application Support/Bruno/default-workspace/workspace.yml",
        "BRUNO_MCP_ALLOWED_ROOTS": "/Users/me/projects/apis",
        "BRUNO_CLI_PATH": "/opt/homebrew/bin/bru"
      }
    }
  }
}

Tool catalog

Discovery

• list_workspaces

• list_collections

• get_collection

• list_items

• get_request

• list_environments

• get_environment

list_workspaces, list_collections, list_items, and list_environments accept limit and an opaque cursor. Their paged responses include total, returned, truncated, and nextCursor. list_workspaces returns summaries (path, name, revision, status, and collectionCount) rather than embedding registration arrays. list_collections pages one flattened record per workspace registration; each record includes workspace identity plus collection name, path, status, and format when available. Its collections.snapshotToken identifies the listing snapshot. Pass nextCursor unchanged, and restart traversal if a workspace registration changes and a later page reports a revision conflict. Collection item and environment pages similarly include collectionRevision.

Collections and workspaces

• create_collection

• update_collection

• move_collection

• register_collection

• unregister_collection

• delete_collection

Folders, requests, and environments

• create_folder, update_folder, move_folder, delete_folder

• create_request, update_request, move_request, delete_request

• create_environment, update_environment, move_environment, delete_environment

Variables and secrets

• set_variables

• delete_variables

• set_secret

• rename_secret

• delete_secret

Execution

• run_request

• run_folder

• run_collection

Execution supports environments, non-secret runtime overrides, recursion, include/exclude tags, bail, tests-only mode, safe/developer sandboxes, CA and client certificates, proxy disabling, CSV/JSON data files, iterations, delay, and timeout. Developer sandbox and insecure TLS require their explicit matching opt-in flags.

Security model

• Collection access is restricted to canonical allowed roots.

• Traversal, absolute item paths, reserved metadata names, mixed formats, and symlink escapes are rejected.

• Paths are re-resolved immediately before reads, writes, moves, runs, and trash operations.

• Mutations are serialized per collection and use atomic writes.

• Folder and collection directory moves require an atomic same-filesystem rename. Cross-filesystem moves are rejected with CROSS_DEVICE_MOVE_UNSUPPORTED; use an explicit copy/import workflow instead.

• Read results contain SHA-256 revisions. Mutation tools require the matching expectedRevision, preventing silent overwrites after Desktop edits.

• All delete_* tools require confirm: true and use the OS trash. There is no permanent-delete fallback.

• bru is spawned directly without a shell. Output and reports are bounded.

• Safe sandboxing and TLS verification are defaults.

Secret behavior

set_secret writes the value to the native OS credential store. Bruno files contain only the variable name and secret marker. get_environment returns the secret name and present state, never its value.

For a run, the server builds an owner-only temporary environment file containing the selected environment's regular variables and managed secrets, passes its path to bru, and removes it in a finally path. Secret values are not placed in argv, logs, or MCP responses. Exact values and common sensitive headers are redacted from CLI output and parsed reports. Secret namespaces migrate with environment/collection moves and are removed with confirmed environment or collection deletion.

Examples

Examples below show tools/call arguments; paths must be allowed.

List registered and discovered collections (pass the returned nextCursor to continue):

{ "name": "list_collections", "arguments": { "discover": true, "limit": 100 } }

Create a legacy collection:

{
  "name": "create_collection",
  "arguments": {
    "root": "/Users/me/projects/apis/example",
    "name": "Example API",
    "format": "bru",
    "register": true
  }
}

Create a request:

{
  "name": "create_request",
  "arguments": {
    "collectionRoot": "/Users/me/projects/apis/example",
    "parentPath": "Users",
    "name": "List Users",
    "item": {
      "type": "http-request",
      "request": {
        "method": "GET",
        "url": "{{baseUrl}}/users",
        "headers": [],
        "params": [],
        "body": { "mode": "none" }
      }
    }
  }
}

Update it using the revision returned by get_request:

{
  "name": "update_request",
  "arguments": {
    "collectionRoot": "/Users/me/projects/apis/example",
    "relativePath": "Users/List Users.bru",
    "expectedRevision": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "patch": { "description": "Returns all users" }
  }
}

Run a request:

{
  "name": "run_request",
  "arguments": {
    "collectionRoot": "/Users/me/projects/apis/example",
    "relativePath": "Users/List Users.bru",
    "environment": "local",
    "runtimeOverrides": { "page": 1 },
    "timeoutMs": 30000
  }
}

Delete it explicitly:

{
  "name": "delete_request",
  "arguments": {
    "collectionRoot": "/Users/me/projects/apis/example",
    "relativePath": "Users/List Users.bru",
    "expectedRevision": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "confirm": true
  }
}

Troubleshooting

• Workspace missing/unreadable: set BRUNO_MCP_WORKSPACE_PATHS to the exact workspace.yml path and verify filesystem permissions.

• Path outside allowed roots: add the collection's parent to BRUNO_MCP_ALLOWED_ROOTS; restart the MCP server after configuration changes.

• Revision conflict: re-read the collection/item/environment and retry with the new revision. Do not reuse a stale revision.

• Cross-filesystem directory move rejected: move_folder and move_collection never fall back to copy-and-delete. Copy or import into the destination through an explicit separate workflow.

• bru spawn failure: run $BRUNO_CLI_PATH --version in the same environment as the MCP client.

• Secret store unavailable: unlock/configure the platform's native credential service. The server intentionally does not fall back to plaintext.

• Run report missing or malformed: run the same target with bru run directly and verify CLI 4.0.0 compatibility.

• Desktop does not immediately refresh: reopen/reload the collection in Bruno Desktop; the server guarantees durable files, not UI focus/refresh.