bruno-mcp

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.

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.

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.brufile 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 the agent that helps me to maintain this server to explain how its experience with Bruno had beenwithoutthe 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.brufile right and the details wrong — and Bruno never complains. It reads the keys it recognises and ignores the rest. A single-linetags: smokelooks tagged and meansuntaggedto the runner. Write a tags list the obvious way and it lands on disk one character per line. This server once wrote.ymlvariables 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 intoruntimeand 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.

- 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_requesttouches the fields you passed and leaves the rest of the file alone
- It can read before it writes—read_requestreturns structured JSON, the same shape for both formats
- It runs the requests itself— vars, auth, assertions, dependency ordering, nobrubinary 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

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

The server does not wrap thebrubinary — 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,selecteddefaults, 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 withBruno'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 matchesbru 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.

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).

RequiresNode.js >= 22. CI tests 22.x and 24.x.

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.

Pick one of the others if: you wantthe 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 tounderstand a large existing collectionwithout 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 thebruCLI in your image and only ever need "run this collection" (hungthai1401); or you want the agent tocall your API through your existing requestsas if each were a native tool (djkz).

Pick this one if: you want the agent towritethe collection and not just read or run it, you are on.ymlopencollection format, you need the run to happenwithout 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-mcpregisters eight tools —create_collection,create_request,create_environment,create_crud_requests,create_test_suite,add_test_script,list_collections,get_collection_stats. It writes.brufiles and does not read a request back, run anything, or expose an edit tool; aupdateRequesthelper exists in itssrc/bruno/request.tsbut no MCP tool reaches it.

git clone https://github.com/Ostico/bruno-mcp-studio.git cd bruno-mcp-studio npm install # npm, not yarn — the yarn lockfile is stale npm run build

command: npx args: ["-y", "@ostico/bruno-mcp"]

claude mcp add bruno -- npx -y @ostico/bruno-mcp

Claude Desktop, Claude Code, Cursor, Codex CLI, opencode, Windsurf, Zed, Cline, Continue, LM Studio, Gemini CLI, MCP Inspector, your own SDK client — all the same server. Nothing below is a compatibility list; it is just where each client keeps its config.

{ "mcpServers": { "bruno-mcp": { "command": "npx", "args": ["-y", "@ostico/bruno-mcp"], "env": {} } } }

Running a clone, or a pinned install, is the same config with"command": "node"and"args": ["/absolute/path/to/dist/index.js"].

Config schemas are the client's, not this server's, and they move. If a client's format differs from the JSON above, follow the client's docs; onlycommandandargsmatter here.

SeeINTEGRATION.mdfor worked examples, Docker, and troubleshooting.

// 1. create a collection { "name": "my-api", "outputPath": "./collections", "baseUrl": "https://api.example.com" } // 2. add a request with a test { "collectionPath": "./collections/my-api", "name": "Get Users", "method": "GET", "url": "{{baseUrl}}/users", "scripts": { "tests": "test(\"ok\", function() { expect(res.getStatus()).to.equal(200); });" } } // 3. run it { "collectionPath": "./collections/my-api" }

{ "collectionPath": "./collections/my-api", "environment": "dev", "requests": ["auth/login.bru", "users"] }

A directory inrequestsexpands to the requests under it, ordered byseqwithin each folder, subfolders first, ties broken by filename. Duplicates are honoured: naming a request twice runs it twice.

By default nothing stops a run early. A request that fails, a file that will not parse, a name that matches nothing — each is reported and the run continues.

bail: truestops the run at the first request that fails or whose tests fail. Twenty-three requests behind a login that stopped working is twenty-three failures for one cause, and the cause is the least visible of them.

{ "collectionPath": "./collections/my-api", "bail": true }

Everything the run did not reach comes back in place, markedskipped: truewithskipReason: "bail", carrying the method and URL it would have sent. Those requests are counted insummary.skippedand inneitherpassednorfailed, sopassed + failedstill equalstotaland a truncated run cannot read as a shorter one that went green. The run itself gains abailobject:

{ "bail": { "reason": "test failure", "at": "Login", "path": "/collections/my-api/auth/login.bru", "group": 0, "skipped": 22 } }

reasonis eitherrequest failure(nothing came back) ortest failure(it came back and a check failed). Later groups are skipped whole.

Nothing cancels a request already in flight. Withparallel, or with a group of its own that runs concurrently, the requests that had already started still finish and are reported normally — the run says so inwarningsrather than leaving you to infer it from the count.

{ "collectionPath": "./collections/my-api", "parallel": true, "groups": [ { "name": "alice", "requests": ["auth/login.bru", "orders"], "variables": { "user": "alice" } }, { "name": "bob", "requests": ["auth/login.bru", "orders"], "variables": { "user": "bob" } } ] }

parallel: trueruns the two groups against each other. Each group's own requests stay serial, which is what you want whenordersdepends on the login before it.

{ "groups": [ { "name": "staging", "requests": ["smoke"], "environment": "staging" }, { "name": "production", "requests": ["smoke"], "environment": "production" } ] }

Group fields:name,requests,environment,variables,parallel,startAfter,data,dataFile.

docs/execution-groups.mdcovers the whole model: what a group owns, the twoparallelflags and their defaults, ordering, iterations over data rows, the concurrency ceiling, and what a failure looks like at each level.

- Omitrequeststo run thewhole collectionunder that group's identity. An empty[]runs nothing.
- environmentreplacesthe run-level one;variablesmergeover the run-level ones, group winning.
- Setparallelon a group to run its own requests concurrently. They share that group's store, so they can genuinely contend on abru.setVar— the point when reproducing a race. GivemaxConcurrencyat least as many slots as racers, or the cap serialises them quietly.
- startAfter: { group, requestsCompleted }holds a group until another has got that far — a listener connected before a trigger fires, without abru.sleeptuned to that day's latency. Needs run-levelparallel; a request that failed still counts as a position reached; cycles and gates that could never open are refused before anything runs.

Results are group-shaped. There isno top-levelresultsarray, not even when you passed nogroups— that case is one group, and flattening it would make every caller check which way they had called.

Each group carries its ownsummary,results,missingRequests,capturedVariableNames,capturedVariablesandwarnings. The top-levelsummarycovers the whole run.

A group that could not start at all reportserrorinstead of results and counts as one failure — otherwise a run with a dead group would read green.

Run-level fields:parseErrorsandparseFailuresname files that could not be parsed,warningscollects anything else worth seeing.

Scripts run in a V8 context inside a forked process (seeSecurity). Both kinds are async functions, so top-levelawaitworks.

Wrap assertions intest().A bare passingexpect()is never recorded, so the run reports"tests": []while the request counts as passed — green with nothing asserted. The runner spots this and says so in that result'swarnings. A barefailingassertion is not silent: it throws and is reported as a script error.

test("status is 200", function() { // ✅ recorded expect(res.getStatus()).to.equal(200); }); expect(res.getStatus()).to.equal(200); // ❌ runs, passes, reported nowhere

Do notJSON.parse(res.getBody()).It is already an object whenever the media type's subtype isjsonor carries the+jsonsuffix —application/json,text/json,application/vnd.api+json— so parsing again throwsSyntaxError: "[object Object]" is not valid JSON. Read fields directly. If an endpoint may return either, branch:typeof b === "string" ? JSON.parse(b) : b.

Reading a claim out of a tokenneeds no second request.atobandbtoaare both present, under the names Bruno's own sandbox uses, so the usual base64url dance works:

test("the token is for the user we logged in as", function() { const payload = res.getBody().token.split(".")[1]; const claims = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/"))); expect(claims.uid).to.equal(bru.getVar("expectedUid")); });