bruno-mcp-studio

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

[![npm version](https://img.shields.io/npm/v/@ostico/bruno-mcp)](https://www.npmjs.com/package/@ostico/bruno-mcp)
[![npm downloads](https://img.shields.io/npm/dw/@ostico/bruno-mcp)](https://www.npmjs.com/package/@ostico/bruno-mcp)
[![node](https://img.shields.io/node/v/@ostico/bruno-mcp)](https://nodejs.org)
[![license](https://img.shields.io/npm/l/@ostico/bruno-mcp)](./LICENSE)

**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](https://modelcontextprotocol.io) server for
[Bruno](https://www.usebruno.com) collections. In August 2026 Bruno's own team announced
an official one, [`usebruno/bruno-mcp`](https://github.com/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](https://github.com/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`](https://github.com/TheDMPV/bruno-mcp) | Read-only index and search over a collection | no | Ranked search, sanitised contracts, stored examples | no | both | no | 8 |
| [hungthai1401/bruno-mcp](https://github.com/hungthai1401/bruno-mcp) | Runs a collection | no | no | Yes, via the CLI | `.bru` | **yes** | run only |
| [jcr82/bruno-mcp-server](https://github.com/jcr82/bruno-mcp-server) | Runs and inspects collections, with report files | no | Yes | Yes, via the CLI | `.bru` | **yes** | 9 |
| [djkz/bruno-api-mcp](https://github.com/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](https://github.com/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,