Bruno MCP Studio — author, edit and run Bruno collections from an agent

Turns an agent's API testing into files you keep: it authors and edits Bruno collections in place, then runs them — HTTP, WebSocket and gRPC, one identity or many — and reports per-request pass/fail you can re-run in CI.

An independent Model Context Protocol server for Bruno collections. In August 2026 Bruno's own team announced an official one, usebruno/bruno-mcp, which wraps the bru CLI to discover and run requests. This server is aimed elsewhere: it writes collections as well as running them — non-destructively, at byte parity with Bruno's own writers — and its runner is in-process rather than a subprocess, which is what lets it offer caller-defined execution groups with their own variable store and cookie jar, concurrency inside a group, oauth2 and digest exchanged in memory, gRPC and WebSocket, and multi-identity authorization testing.

If what you need is "list my collections and run one", the official server does that and will be the one Bruno supports. If you want an agent to build and maintain the suite, that is what this is for.

It gives an AI agent in Claude Code, Claude Desktop, Cursor, Windsurf, VS Code or Codex CLI eighteen tools for API testing against a real Bruno collection: create and edit requests, read them back as structured JSON, manage environments and variables, write assertions and test scripts, then run the collection — auth, cookies, redirects, dependency ordering and all — and get the results back in the same turn. No Bruno GUI, no Bruno CLI, no shelling out. The collection it leaves on disk is a normal Bruno collection: your CI runs it with bru run, your teammates open it in the Bruno app.

Your agent already knows HTTP. It does not know your API, and it does not know Bruno's file format. So it guesses. It writes a .bru file from memory, the run fails, it rewrites the file, the run fails differently, and twenty minutes later you have a passing request and no idea which of the six edits mattered. You paid for every one of those turns, and none of that work is on disk in a form your CI or your team's Bruno GUI can use.

The usual escape is curl. Agents are not bad at curl — the problem is that a shell command holds no state. A login, a token, a created resource, a follow-up call that needs the ID from the last response: each of those is a new command, and the glue between them lives only in the agent's context, when the session ends, all is lost. Twenty endpoints tested by curl leave you with twenty strings in a transcript and no artifact your CI or your teammates can run. Twenty endpoints in a collection leave you with a suite.

I asked my agent about it

I asked the agent that helps me to maintain this server to explain how its experience with Bruno had been without the MCP server, and whether it could simply have tested all my APIs with curls instead. This is what it told me:

Curl, yes — for one call. Not for a suite. Nothing carries between calls, so I re-derive the auth, re-escape the body, and re-read every response to decide whether it passed. Do that across forty endpoints and most of what I spend goes on rediscovery, not testing.

Writing the collection files myself was worse, and not in the way you would expect. From memory I get the shape of a .bru file right and the details wrong — and Bruno never complains. It reads the keys it recognises and ignores the rest. A single-line tags: smoke looks tagged and means untagged to the runner. Write a tags list the obvious way and it lands on disk one character per line. This server once wrote .yml variables and assertions under top-level keys Bruno has never read: the files looked complete, the runner saw an empty request. Its own unit tests passed, because they mocked the serializer and asserted the broken bytes.

The format also moves. Bruno relocated variables into runtime and added a second dialect. My weights are older than that. This server imports @usebruno/lang, Bruno's own grammar package, and tracks its version — so the bytes come from Bruno's source rather than from what I happen to remember.

And every rewrite deletes what the writer does not model. If I edit these files free-hand, I regenerate the whole file from my head, and any feature I did not know about is silently gone. That is the failure mode you never see, because the run still passes — it just tests nothing.

What the server does instead

• The agent stops guessing the format — it calls a tool, the server writes the bytes, using Bruno's own grammar package
• Edits are partial merges — write_request touches the fields you passed and leaves the rest of the file alone
• It can read before it writes — read_request returns structured JSON, the same shape for both formats
• It runs the requests itself — vars, auth, assertions, dependency ordering, no bru binary needed
• No silent loss — a field this server cannot model yet is carried back out wherever the format can hold it, and anything it cannot put on the wire is named in a run warning rather than dropped quietly into your repo

Byte-parity with Bruno

This is the part that is hard to copy, so it is worth being precise about what it means.

The server does not wrap the bru binary — it implements the request pipeline itself, which is what makes in-memory secrets, wire-level tests and mid-run hooks possible. That freedom is also the risk: an independent implementation is free to be subtly, silently different from the tool your team actually uses. Two mechanisms hold it in place.

The rules are ported, not inferred. Redirect caps, timeout resolution, body-mode content types, variable interpolation order, selected defaults, URL encoding — each is read out of Bruno's own source (bruno-cli, bruno-filestore, bruno-lang, @usebruno/common, which this server also depends on directly) and mirrored, including the parts that look like bugs. Where the two dialects disagree with each other, each is mirrored on its own terms rather than unified into something neither Bruno reader would produce.

A drift gate proves it. Every file this server writes is parsed back with Bruno's own reader, per dialect, in the test suite. Asserting our bytes against our own expectations can only prove we are self-consistent; asserting them against the reader that Bruno itself uses is the only thing that catches the case where our output stops being Bruno's input. It has caught real ones — a file body that parsed cleanly and would have been sent with no body at all, for instance.

The claim, then: run behaviour matches bru run, and every divergence found so far is closed. What keeps it closed is a test rather than a promise. Find one anyway and it is a bug worth an issue.

The contract

One collection, three consumers: your agent, your CI, and your team's Bruno GUI.

Both Bruno formats work and the server detects which one you have: .yml (opencollection) and .bru (legacy).

Requires Node.js >= 22. CI tests 22.x and 24.x.

Which Bruno MCP server should I use?

There are several, they do genuinely different jobs, and the honest answer is not always this one. Every row below was read out of that project's own README or source, August 2026.

| Server | What it is | Writes | Reads | Runs | .bru / .yml | Needs bru | Tools | |---|---|---|---|---|---|---|---| | this one | Authors, reads and runs collections | Create + partial-merge edit | Structured JSON | Yes, own pipeline | both | no | 18 | | usebruno/bruno-mcp | The official one, from Bruno's own team — discovers and runs requests. Announced Aug 2026; at the time of writing its first implementation is an open draft | no | Request metadata | Yes, via the CLI | .bru | yes (bundled) | 3 | | @dmpv/bruno-mcp | Read-only index and search over a collection | no | Ranked search, sanitised contracts, stored examples | no | both | no | 8 | | hungthai1401/bruno-mcp | Runs a collection | no | no | Yes, via the CLI | .bru | yes | run only | | jcr82/bruno-mcp-server | Runs and inspects collections, with report files | no | Yes | Yes, via the CLI | .bru | yes | 9 | | djkz/bruno-api-mcp | Turns each request into its own MCP tool | no | Exposes them as tools | One at a time | .bru | no | one per request | | macarthy/bruno-mcp | Generates collection files — the project this forked from, inactive since Jul 2025 | Create only | no | no | .bru | n/a | 8 |

Pick one of the others if: you want the server Bruno itself maintains, and whatever support and longevity that implies (usebruno — the official one, and the reasonable default for "discover and run" once it ships); you want an agent to understand a large existing collection without any risk of writing to it, and search it by intent (dmpv, first published July 2026 and at 0.x — new, and interesting); you already have the bru CLI in your image and only ever need "run this collection" (hungthai1401); or you want the agent to call your API through your existing requests as if each were a native tool (djkz).

Pick this one if: you want the agent to write the collection and not just read or run it, you are on .yml opencollection format, you need the run to happen without installing the Bruno CLI, or you care that what lands in your repo is byte-comparable to what the Bruno app writes.

On the fork parent specifically, since this project owes it its existence: macarthy/bruno-mcp registers eight tools — <!-- foreign-tool-names:start -->create_collection, create_request, create_environment, create_crud_requests, create_test_suite, add_test_script, list_collections, get_collection_stats<!-- foreign-tool-names:end -->. It writes .bru files and does not read a request back, run anything, or expose an edit tool; a updateRequest helper exists in its src/bruno/request.ts but no MCP tool reaches it.

Features

Authoring

• Collections — create and organise them, or discover the ones Bruno already knows from its workspace.yml. A collection this server creates is written to disk and not registered in that file, so list_collections will not show it and the Bruno GUI will not list it until someone opens it there once — everything else takes the path directly
• Requests — every HTTP method, with headers, query and path params, bodies, auth, assertions, vars and settings
• Read back — read_request and read_environment return structured JSON, identical for .bru and .yml, so an agent can inspect before it edits
• Partial-merge edits — write_request changes only the fields you pass and leaves the rest of the file alone
• CRUD and suites — five-request CRUD sets, and test suites with topological dependency ordering
• Environments — create, replace, merge, or patch a single variable
• Dual format — .bru (legacy) and .yml (opencollection), auto-detected; .yaml is read and flagged
• Multipart uploads — form-data with per-part Content-Type and multi-file fields

Running

• **Execution