Bruno MCP Server

An MCP (Model Context Protocol) server that intelligently generates and maintains Bruno API test collections. Automatically create comprehensive test suites for CRUD JSON APIs by simply telling Claude about your endpoints.

Overview

The Bruno MCP Server bridges the gap between API development and testing by enabling LLMs to generate valid, maintainable Bruno collections. Instead of manually writing API tests, developers describe their API changes and the server generates ready-to-run test collections that validate the behavior.

Current Focus: CRUD JSON APIs with environment-based URL configuration.

Related MCP server: Bruno MCP Server

Features

MVP (Minimum Viable Product)

• Auto-Generate Tests for Endpoint Changes

  • New endpoints: Create tests that validate successful behavior

  • Updated endpoints: Create tests for modified behavior

  • Removed endpoints: Create tests that validate endpoints return expected error responses

• Environment-Driven Configuration

  • Single environment variable (BRUNO_API_URL) for base URL

  • Support both localhost development and remote endpoints

  • Generated collections inherit the environment configuration

• Best Practice Alignment

  • Server leverages Bruno documentation for test patterns

  • Follows API testing conventions

  • Generates human-readable, maintainable collections

• Incremental Complexity

  • MVP handles straightforward CRUD operations

  • Foundation for future enhancements (auth, complex assertions, workflows, etc.)

Quick Start

Installation

git clone <this-repo>
cd bruno-mcp-server
npm install
npm run build

Running the server

The server communicates over stdio (standard MCP transport):

npm start
# or directly:
node dist/index.js

Configuring in Roo Code

Roo Code (and other MCP clients) launch the server as a subprocess and talk to it over stdio. Add an entry to Roo Code's MCP settings (mcp settings.json / .roo/mcp.json, depending on scope):

{
  "mcpServers": {
    "bruno": {
      "command": "node",
      "args": ["/absolute/path/to/bruno-mcp-server/dist/index.js"]
    }
  }
}

No environment variables are required to start the server itself — the BRUNO_API_URL value lives inside the generated Bruno environment file (environments/development.bru) so it can differ per collection and be edited directly in Bruno.

Usage Example

From Roo Code, ask the assistant to use the generate_bruno_test tool, e.g.:

"I just added a POST /users endpoint that creates a new user.
It accepts {name, email} and returns the created user with an id.
Generate a Bruno test for it in ./bruno"

This calls the tool with arguments like:

{
  "collectionPath": "./bruno",
  "name": "create-user",
  "changeType": "new",
  "method": "post",
  "path": "/users",
  "description": "Create a new user",
  "requestBody": { "name": "Test User", "email": "test@example.com" }
}

The server will:

1. Create the Bruno collection scaffold (.bruno/bruno.json, environments/development.bru) if it doesn't already exist

2. Write a new .bru request file with the appropriate method, URL (using {{BRUNO_API_URL}}), body, and status assertion

3. For changeType: "removed", generate a request that asserts the endpoint now fails (defaults to expecting 404)

User Stories & Acceptance Criteria

User Story 1: Generate Tests for New CRUD Endpoints

As a developer adding a new API endpoint
I want to automatically generate tests for my endpoint
So that I can quickly validate it works without manually writing test cases

Acceptance Criteria:

• Server accepts description of a new endpoint (method, path, request body, expected status)

• Server generates a Bruno collection with the endpoint

• Generated requests use {{BRUNO_API_URL}} environment variable for the base URL

• Request includes appropriate HTTP method and path

• Request includes sample data matching the request body

• Test includes assertion for expected status code

• Test includes assertion validating response JSON structure matches expected schema (planned — see Roadmap)

• Collection file is properly formatted and can be opened in Bruno

User Story 2: Generate Tests for Updated Endpoints

As a developer modifying an existing endpoint
I want to regenerate tests to reflect the new behavior
So that I can verify my changes don't break existing functionality

Acceptance Criteria:

• Server accepts description of an updated endpoint (new method/path/body/status)

• Server generates a Bruno test reflecting the new behavior (changeType: "updated")

• Generated tests use {{BRUNO_API_URL}} environment variable

• Server automatically replaces/diffs the previous version of the request rather than requiring the same name (planned — see Roadmap; today re-running with the same name overwrites the file)

User Story 3: Generate Tests for Removed Endpoints

As a developer removing or deprecating an endpoint
I want to create tests that validate the endpoint no longer works as expected
So that I can ensure the endpoint has been properly removed or returns appropriate error responses

Acceptance Criteria:

• Server accepts description of a removed endpoint (path, previous HTTP method)

• Server generates a Bruno test for the removed endpoint

• Test attempts to call the removed endpoint using {{BRUNO_API_URL}}

• Test includes an assertion validating the status code (defaults to 404, overridable via expectedStatus for 410/5xx/etc.)

• Assertion can validate the response body indicates the endpoint no longer exists (status-code-only for now) (planned — see Roadmap)

• Collection file is properly formatted and can be opened in Bruno

Architecture

Current (MVP) implementation:

bruno-mcp-server/
├── src/
│   ├── index.ts             # MCP server entry point; registers the
│   │                        # generate_bruno_test tool, handles collection
│   │                        # scaffolding and file writes
│   └── brunoGenerator.ts    # Pure functions that build .bru file contents,
│                             # bruno.json, and the development environment file
├── dist/                    # Compiled output (npm run build)
├── README.md
├── package.json
└── tsconfig.json

As the server grows (schema-based response assertions, auth, multiple environments, etc.) this will likely split into handlers/, services/, and models/ as originally sketched — kept flat for now since there's a single tool.

Design Decisions

Environment Variable Over Hardcoded URLs

The server uses ${BRUNO_API_URL} as an environment variable in generated requests. This allows developers to:

• Test against localhost during development

• Test against staging/production with a single environment variable change

• Share collections across team members with different configurations

JSON-Based Schema Input

The server accepts endpoint descriptions in structured JSON format, making it:

• Parseable by LLMs

• Compatible with programmatic API documentation

• Extensible for future features

Bruno Collection Format

Collections are generated as valid Bruno .bru files (or collections format) that:

• Are human-readable and editable

• Can be opened, modified, and run in the Bruno UI

• Support environment variable substitution

• Include test assertions

Roadmap

Phase 2: Enhanced Test Generation

• Support for authentication (Bearer tokens, API keys)

• Parameterized tests for multiple scenarios

• Custom assertion generation based on response schemas

• Negative test case generation (invalid inputs, edge cases)

Phase 3: Advanced API Support

• GraphQL API support

• Webhook testing

• Async operation testing (polling, callbacks)

• Request/response transformation pipelines

Phase 4: Developer Experience

• CLI for generating collections locally

• VS Code extension for inline test generation

• Integration with OpenAPI/Swagger specifications

• Test result aggregation and reporting

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/my-feature)

3. Add tests for new functionality

4. Submit a pull request

For major changes, please open an issue first to discuss proposed changes.

License

MIT

Support

• Documentation: See /docs for detailed guides

• Issues: Report bugs and request features on GitHub

• Discussions: For questions and community discussion

Technical Notes for Implementation

Bruno Collection Structure

Generated collections should conform to Bruno's directory structure:

my-collection/
├── .bruno
│   └── bruno.json          # Collection metadata
├── endpoints/
│   ├── users/
│   │   ├── create.bru      # POST /users
│   │   ├── list.bru        # GET /users
│   │   ├── get.bru         # GET /users/{id}
│   │   ├── update.bru      # PUT /users/{id}
│   │   └── delete.bru      # DELETE /users/{id}
│   └── posts/
│       └── ...
└── environments/
    └── development.bru     # Environment variables

Schema Input Format

When describing endpoints, provide:

{
  "endpoint": {
    "method": "POST",
    "path": "/users",
    "description": "Create a new user",
    "requestBody": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      },
      "required": ["name", "email"]
    },
    "responseBody": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "email": { "type": "string" },
        "createdAt": { "type": "string", "format": "date-time" }
      }
    },
    "successStatusCode": 201
  }
}

Best Practices Reference

The server should embed knowledge of Bruno testing best practices:

• Clear, descriptive request names

• Proper HTTP method usage

• Meaningful assertions (not just status codes)

• Environment variable usage for configuration

• Consistent naming conventions

• Request/response documentation in comments

This README doubles as the working spec for the server. The "Technical Notes" and JSON schema examples above describe the target shape of tool inputs; the current MVP (single generate_bruno_test tool, see Quick Start) implements a subset of it and will grow into the rest per the Roadmap.