Bruno MCP

A read-only Model Context Protocol server and indexer for Bruno API collections.

Bruno MCP discovers classic .bru and OpenCollection YAML (.yml/.yaml) request files, parses them with Bruno's official filestore package, builds a sanitized AI-oriented index, and gives MCP clients deterministic tools for endpoint discovery. It never sends API requests.

Status: early 0.x release. The index schema may evolve before 1.0.

Features

• Automatic recursive discovery of .bru and OpenCollection YAML requests
• Mixed-format collection support during gradual migrations
• Official Bruno parser via @usebruno/filestore
• HTTP, GraphQL, gRPC, and WebSocket request indexing
• Sanitized contracts that omit header, parameter, and auth values
• Explainable, field-aware search with scores and matched fields
• Explicit and folder-derived tags
• Versioned persistent JSON index with source fingerprints
• Automatic loading of fresh docs/api-index.json or .bruno-mcp/api-index.json
• Paginated folder hierarchy with subtree/depth filtering
• Batch contract retrieval by stable endpoint IDs
• Complete saved response examples without extra source parsing
• Automatic reindexing while the MCP server is running
• MCP 2026-07-28 support with automatic fallback for 2025-era clients
• A reusable TypeScript API

Requirements

• Node.js 20.11 or newer
• A Bruno collection directory with bruno.json, opencollection.yml, or request files in either supported format

Quick start

Run the MCP server against a collection:

npx -y @dmpv/bruno-mcp serve ./path/to/collection

Generate a persistent index:

npx -y @dmpv/bruno-mcp index ./path/to/collection \
  --output ./generated/api-index.json

Inspect a collection without writing files:

npx -y @dmpv/bruno-mcp inspect ./path/to/collection

MCP client configuration

Example configuration for clients that support local stdio servers:

{
  "mcpServers": {
    "bruno": {
      "command": "npx",
      "args": [
        "-y",
        "@dmpv/[email protected]",
        "serve",
        "/absolute/path/to/bruno-collection"
      ]
    }
  }
}

The stdio server automatically negotiates MCP 2026-07-28 with modern clients and continues to serve clients that use the 2025 initialization handshake.

Pin a version in team configuration. During local development, replace the package command with node /absolute/path/to/bruno-mcp/dist/cli.js.

MCP tools

| Tool | Purpose | | --- | --- | | list_collections | Describe the active collection | | list_folders | List the folder hierarchy and endpoint counts | | list_endpoints | Filter endpoint summaries | | search_endpoints | Rank endpoints by a text query | | get_endpoint | Get a sanitized contract by ID or method/path | | get_endpoints | Get up to 25 contracts by stable ID in one call | | get_endpoint_examples | Get saved response examples and complete bodies | | get_index_status | Check generation time and parser warnings |

get_endpoint includes method, URL, normalized path, auth mode, body content, field names, documentation, test/assertion presence, source file, and a stable contract hash. Pass include_examples: true to include saved response examples in the same call. Secret-bearing auth, header, and parameter values are not indexed.

get_endpoint_examples returns examples already stored in the index, including the saved response status, content type, and complete body, while omitting the saved request and other response header values.

search_endpoints returns a numeric score and matchedFields with every result. Its default all mode excludes matches found only in low-signal documentation text. Use search_mode: "docs" for an intentional documentation search, or "contract" to ignore docs entirely. Tag filters match both explicit Bruno tags and derivedTags generated from the endpoint folder, method, request type, and known current/legacy roots.

list_folders accepts parent, depth, offset, and limit. get_endpoints accepts at most 25 stable IDs and reports missing IDs without failing the whole batch.

Index command

The generated JSON has a versioned top-level shape:

{
  "schemaVersion": 4,
  "generatedAt": "2026-07-27T00:00:00.000Z",
  "generator": {
    "name": "@dmpv/bruno-mcp",
    "version": "0.6.0"
  },
  "collection": {
    "name": "Example API",
    "endpointCount": 2,
    "sourceFingerprint": "...",
    "formats": ["bru", "opencollection-yaml"]
  },
  "sources": [],
  "folders": [],
  "endpoints": [],
  "warnings": []
}

The default output is .bruno-mcp/api-index.json, which is ignored by Git. Choose a tracked output path when the index is intended as a versioned build artifact. serve automatically checks docs/api-index.json and .bruno-mcp/api-index.json. It loads a persistent index only when its schema is supported and its source fingerprint matches the current Bruno source files; otherwise it safely rebuilds from source. Each endpoint exposes sourceFormat as either bru or opencollection-yaml. Use serve --index <file> to select an explicit index.

Library API

import {
  buildBrunoIndex,
  searchIndex,
  writeBrunoIndex
} from "@dmpv/bruno-mcp";

const index = await buildBrunoIndex("./collection");
const endpoints = searchIndex(index, {
  query: "create order",
  method: "POST"
});

await writeBrunoIndex(index, "./generated/api-index.json");

Development

npm install
npm run check
npm run dev -- serve ./tests/fixtures/sample-collection

npm run check runs the project's automated validation suite.

Security and scope

Bruno MCP is read-only. Version 0.x does not execute requests, scripts, tests, or assertions. It only parses local files.

Body content is included because it is part of an endpoint contract. Do not put real secrets in request bodies. Auth values, header values, and parameter values are deliberately omitted from the index.

License

MIT