Skip to main content
Glama

Bruno MCP Server

by jcr82
npmGitHub
TypeScript
MIT License
116
1
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Bruno MCP Server

Tests Coverage Function Coverage TypeScript License

An MCP (Model Context Protocol) server that provides integration with Bruno CLI for API testing and collection management.

🚀 Quick Start

Install via NPM (Recommended)

# Install globally npm install -g bruno-mcp-server # Or install locally in your project npm install bruno-mcp-server

Install from Source

# Clone the repository git clone https://github.com/jcr82/bruno-mcp-server.git cd bruno-mcp-server # Install dependencies npm install # Build npm run build # Run tests npm test

Features

Core Features

  • ✅ Run individual API requests from Bruno collections

  • ✅ Run entire collections or specific folders

  • ✅ List all requests in a collection

  • ✅ Environment variable support and validation

  • ✅ Report generation (JSON, JUnit, HTML)

  • ✅ Collection discovery and validation

  • ✅ Request introspection and dry run mode

  • ✅ Health monitoring and performance metrics

  • ✅ Security features (path validation, secret masking)

  • ✅ Caching for optimal performance

  • ✅ Mock CLI mode for testing and CI/CD

Installation

Prerequisites

  • Node.js: Version 20 or higher

  • Bruno Collections: Your existing Bruno API test collections

Option 1: NPM Global Installation

npm install -g bruno-mcp-server

This installs the server globally and makes it available as a command.

Option 2: NPM Local Installation

npm install bruno-mcp-server

Add to your MCP client config using node_modules/.bin/bruno-mcp-server.

Option 3: From Source

  1. Clone the repository:

    git clone https://github.com/jcr82/bruno-mcp-server.git cd bruno-mcp-server npm install npm run build

  2. The built server will be in dist/index.js.

Configuration

For Claude Desktop

Add the following to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

If installed globally via npm:

{ "mcpServers": { "bruno": { "command": "bruno-mcp-server" } } }

If installed from source:

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

If installed locally in a project:

{ "mcpServers": { "bruno": { "command": "node", "args": ["/path/to/project/node_modules/.bin/bruno-mcp-server"] } } }

Usage

Once configured, you can use the following tools through your MCP client:

1. Run a Specific Request

bruno_run_request({ collectionPath: "/path/to/collection", requestName: "Get User", environment: "dev", // optional - environment name or path envVariables: { // optional "API_KEY": "your-key" }, // Report generation options (optional) reporterJson: "./reports/results.json", // JSON report reporterJunit: "./reports/results.xml", // JUnit XML for CI/CD reporterHtml: "./reports/results.html", // HTML report dryRun: false // optional - validate without executing HTTP call })

Dry Run Mode: Set dryRun: true to validate request configuration without executing the HTTP call:

bruno_run_request({ collectionPath: "/path/to/collection", requestName: "Create User", dryRun: true // Validates configuration only - no HTTP call made })

Output:

=== DRY RUN: Request Validation === ✅ Request validated successfully (HTTP call not executed) Request: Create User Method: POST URL: {{baseUrl}}/api/users Configuration Summary: Headers: 2 Body: json Auth: bearer Tests: 3 ℹ️ This was a dry run - no HTTP request was sent.

2. Run a Collection

bruno_run_collection({ collectionPath: "/path/to/collection", environment: "dev", // optional - environment name or path folderPath: "auth", // optional - run specific folder envVariables: { // optional "BASE_URL": "https://api.example.com" }, // Report generation options (optional) reporterJson: "./reports/collection.json", reporterJunit: "./reports/collection.xml", reporterHtml: "./reports/collection.html", dryRun: false // optional - validate without executing HTTP calls })

Dry Run Mode for Collections:

bruno_run_collection({ collectionPath: "/path/to/collection", folderPath: "Users", dryRun: true // Validates all requests without making HTTP calls })

Output:

=== DRY RUN: Collection Validation === ✅ Collection validated successfully (HTTP calls not executed) Total Requests: 5 Requests that would be executed: ✓ Get All Users - GET {{baseUrl}}/users ✓ Get User By ID - GET {{baseUrl}}/users/1 ✓ Create User - POST {{baseUrl}}/users ✓ Update User - PUT {{baseUrl}}/users/1 ✓ Delete User - DELETE {{baseUrl}}/users/1 ℹ️ This was a dry run - no HTTP requests were sent.

3. List Requests

bruno_list_requests({ collectionPath: "/path/to/collection" })

4. Discover Collections

Recursively search for Bruno collections in a directory:

bruno_discover_collections({ searchPath: "/path/to/workspace", maxDepth: 5 // optional - maximum directory depth (default: 5, max: 10) })

Example output:

Found 3 Bruno collection(s): 1. /path/to/workspace/api-tests 2. /path/to/workspace/projects/integration-tests 3. /path/to/workspace/e2e-tests

5. List Environments

List all environments available in a collection:

bruno_list_environments({ collectionPath: "/path/to/collection" })

Example output:

Found 3 environment(s): • dev Path: /path/to/collection/environments/dev.bru Variables: 5 - baseUrl: https://api.dev.example.com - apiKey: *** - timeout: 5000 • staging Path: /path/to/collection/environments/staging.bru Variables: 5 - baseUrl: https://api.staging.example.com - apiKey: *** - timeout: 10000 • production Path: /path/to/collection/environments/production.bru Variables: 5 - baseUrl: https://api.example.com - apiKey: *** - timeout: 15000

6. Validate Environment

Validate an environment file's structure and variables:

bruno_validate_environment({ collectionPath: "/path/to/collection", environmentName: "dev" })

Example output:

=== Environment Validation: dev === ✅ Status: Valid Variables: 5 baseUrl: https://api.dev.example.com apiKey: *** (masked) timeout: 5000 region: us-east-1 debug: true Warnings: ⚠️ Variable "apiKey" may contain hardcoded sensitive data

7. Get Request Details

Inspect a request's configuration without executing it:

bruno_get_request_details({ collectionPath: "/path/to/collection", requestName: "Create User" })

Example output:

=== Request Details: Create User === Method: POST URL: {{baseUrl}}/api/users Auth: bearer Headers: Content-Type: application/json Authorization: Bearer {{token}} Body Type: json Body Content: { "name": "John Doe", "email": "john@example.com", "role": "user" } Tests: 3 1. Status should be 201 2. Response should have an ID 3. Email should match Metadata: Type: http Sequence: 1

Use Cases:

  • Inspect request configuration before execution

  • Debug request setup issues

  • Generate documentation from requests

  • Understand test assertions

  • Review request structure

8. Validate Collection

Validate a Bruno collection's structure, syntax, and integrity:

bruno_validate_collection({ collectionPath: "/path/to/collection" })

Example output:

=== Collection Validation === ✅ Collection is valid Summary: bruno.json: ✓ Found Total Requests: 15 Valid Requests: 15 Invalid Requests: 0 Environments: 3 Warnings: ⚠️ Environment "dev": Variable "apiKey" may contain hardcoded sensitive data 🎉 Collection is ready to use!

Use Cases:

  • Pre-flight validation before deployment

  • CI/CD pipeline checks

  • Catch configuration errors early

  • Verify collection integrity

  • Validate after collection updates

9. Health Check

Check the server health, Bruno CLI availability, and optionally view performance metrics and cache statistics:

bruno_health_check({ includeMetrics: true, // optional - include performance metrics includeCacheStats: true // optional - include cache statistics })

Example output:

=== Bruno MCP Server Health Check === Server Status: Running Server Version: 0.1.0 Node.js Version: v24.8.0 Platform: darwin arm64 Uptime: 42 seconds === Bruno CLI === Status: Available Version: Available (use --version for details) === Configuration === Logging Level: info Retry Enabled: Yes Security Enabled: No restrictions Secret Masking: Enabled Cache Enabled: Yes Cache TTL: 300000ms === Performance Metrics === Total Executions: 15 Success Rate: 100.00% Average Duration: 234.56ms By Tool: bruno_run_request: Executions: 10 Success Rate: 100.00% Avg Duration: 189.23ms === Cache Statistics === Request List Cache: Size: 3 entries Total Hits: 25 Cached Collections: - /path/to/collection1 - /path/to/collection2 - /path/to/collection3 === Status === All systems operational

Report Generation

The Bruno MCP Server supports generating test reports in three formats:

JSON Report

Contains detailed test results in JSON format, ideal for programmatic processing.

JUnit XML Report

Compatible with CI/CD systems like Jenkins, GitHub Actions, and GitLab CI. Perfect for integration into automated pipelines.

HTML Report

Beautiful, interactive HTML report with Vue.js interface for easy viewing in browsers.

Example: Generate All Reports

bruno_run_collection({ collectionPath: "./my-api-tests", environment: "production", reporterJson: "./reports/api-tests.json", reporterJunit: "./reports/api-tests.xml", reporterHtml: "./reports/api-tests.html" })

The server will confirm when reports are generated:

=== Generated Reports === Wrote json results to ./reports/api-tests.json Wrote junit results to ./reports/api-tests.xml Wrote html results to ./reports/api-tests.html

Example Collection

A ready-to-use example collection is available in collection-examples/getting-started. This collection demonstrates:

  • Basic HTTP methods (GET, POST, PUT)

  • Environment variables usage

  • Request headers and bodies

  • Response tests and assertions

  • Report generation

The example uses the free JSONPlaceholder API, so you can run it immediately without any setup.

Quick Start:

bruno_run_collection({ collectionPath: "./collection-examples/getting-started", environment: "dev" })

See the example collection README for more details and usage examples.

Development

Run in Development Mode

npm run dev

Run Tests

npm test

Build

npm run build

Configuration

The Bruno MCP Server supports configuration via a bruno-mcp.config.json file. The server looks for this file in the following locations (in order):

  1. Environment variable: BRUNO_MCP_CONFIG

  2. Current working directory: ./bruno-mcp.config.json

  3. Home directory: ~/.bruno-mcp.config.json

Configuration Options

{ "brunoCliPath": "/custom/path/to/bru", "brunoHome": "/path/to/bruno/home", "timeout": { "request": 30000, "collection": 120000 }, "retry": { "enabled": true, "maxAttempts": 3, "backoff": "exponential" }, "security": { "allowedPaths": [ "/path/to/collections", "/another/path" ], "maskSecrets": true, "secretPatterns": [ "password", "api[_-]?key", "token", "secret", "authorization" ] }, "logging": { "level": "info", "format": "json" }, "performance": { "cacheEnabled": true, "cacheTTL": 300000 } }

Configuration Details

  • brunoCliPath: Custom path to Bruno CLI executable (default: auto-detect)

  • brunoHome: Bruno home directory for environments and settings

  • timeout.request: Timeout for individual requests in milliseconds (default: 30000)

  • timeout.collection: Timeout for collection runs in milliseconds (default: 120000)

  • retry.enabled: Enable automatic retry on failures (default: false)

  • retry.maxAttempts: Maximum retry attempts (1-10, default: 3)

  • retry.backoff: Retry backoff strategy: 'linear' or 'exponential'

  • security.allowedPaths: Restrict file system access to specific paths

  • security.maskSecrets: Enable secret masking in logs and errors (default: true)

  • security.secretPatterns: Additional regex patterns for secret detection

  • logging.level: Log level: 'debug', 'info', 'warning', 'error' (default: 'info')

  • logging.format: Log format: 'json' or 'text' (default: 'text')

  • performance.cacheEnabled: Enable request list caching (default: true)

  • performance.cacheTTL: Cache time-to-live in milliseconds (default: 300000)

See bruno-mcp.config.example.json for a complete example.

Security Features

Path Validation

The server validates all file paths to prevent directory traversal attacks. Configure security.allowedPaths to restrict access to specific directories.

Input Sanitization

All user inputs are sanitized to prevent command injection and other security vulnerabilities.

Secret Masking

Sensitive data (API keys, passwords, tokens) are automatically masked in logs and error messages. Customize detection patterns via security.secretPatterns.

Environment Variable Validation

Environment variables are validated for safe characters and patterns before being passed to Bruno CLI.

Performance Features

Request List Caching

Collection request lists are cached in memory with configurable TTL to reduce file system operations. Cache hits are logged for monitoring.

Execution Metrics

The server tracks performance metrics including:

  • Execution duration per tool

  • Success/failure rates

  • Average response times

  • Total executions

Access these metrics via the bruno_health_check tool with includeMetrics: true.

Project Structure

bruno-mcp-server/ ├── src/ │ ├── index.ts # Main MCP server implementation │ ├── bruno-cli.ts # Bruno CLI wrapper │ ├── config.ts # Configuration management │ ├── security.ts # Security validation utilities │ └── performance.ts # Caching and metrics tracking ├── dist/ # Compiled JavaScript (after build) ├── bruno-mcp.config.json # Active configuration ├── bruno-mcp.config.example.json # Example configuration ├── package.json ├── tsconfig.json └── README.md

Error Handling

The server properly handles and reports:

  • Missing Bruno CLI installation

  • Invalid collection paths

  • Unsupported Bruno CLI operations

  • Request execution failures

  • Malformed input parameters

Documentation

📚 Guides

🔧 API Reference

  • MCP Tools API - Complete reference for all 9 MCP tools with examples

Troubleshooting

For detailed troubleshooting, see the Troubleshooting Guide.

Quick Fixes

Bruno CLI Not Found:

  1. Ensure dependencies are installed: npm install

  2. Verify Bruno CLI was installed: npx bru --version

  3. The server will automatically use the local installation in node_modules/.bin/bru

Collection Not Found:

  • Use absolute paths (not relative paths)

  • Verify the collection path is correct

  • Ensure the directory contains a bruno.json file

Permission Issues:

  • Ensure the MCP server has read access to your Bruno collections

  • Check that the server can execute the Bruno CLI

Next Steps

See ROADMAP.md for the complete feature roadmap.

Completed features:

  • ✅ Core MCP server with Bruno CLI integration

  • ✅ Run requests and collections

  • ✅ Environment support

  • ✅ Report generation (JSON, JUnit, HTML formats)

  • ✅ Collection discovery (recursive search)

  • ✅ Environment management (list, validate)

  • ✅ Request introspection (inspect without executing)

  • ✅ Dry run mode (validate without HTTP execution)

  • ✅ Collection validation (structure, syntax, integrity checks)

  • ✅ Configuration system with multi-location support

  • ✅ Security hardening (path validation, input sanitization, secret masking)

  • ✅ Performance optimizations (request list caching, execution metrics)

  • ✅ Health check tool

Planned enhancements:

  • Logging system with structured output

  • Parallel execution support

  • Advanced filtering and search capabilities

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

Integrates Bruno CLI for API testing, enabling users to run API requests and collections, manage environments, generate test reports (JSON/JUnit/HTML), and validate collection structures through natural language commands.

  1. 🚀 Quick Start
    1. Install via NPM (Recommended)
    2. Install from Source
  2. Features
    1. Core Features
  3. Installation
    1. Prerequisites
    2. Option 1: NPM Global Installation
    3. Option 2: NPM Local Installation
    4. Option 3: From Source
  4. Configuration
    1. For Claude Desktop
  5. Usage
    1. 1. Run a Specific Request
    2. 2. Run a Collection
    3. 3. List Requests
    4. 4. Discover Collections
    5. 5. List Environments
    6. 6. Validate Environment
    7. 7. Get Request Details
    8. 8. Validate Collection
    9. 9. Health Check
  6. Report Generation
    1. JSON Report
    2. JUnit XML Report
    3. HTML Report
    4. Example: Generate All Reports
  7. Example Collection
    1. Development
      1. Run in Development Mode
      2. Run Tests
      3. Build
    2. Configuration
      1. Configuration Options
      2. Configuration Details
    3. Security Features
      1. Path Validation
      2. Input Sanitization
      3. Secret Masking
      4. Environment Variable Validation
    4. Performance Features
      1. Request List Caching
      2. Execution Metrics
    5. Project Structure
      1. Error Handling
        1. Documentation
          1. 📚 Guides
          2. 🔧 API Reference
        2. Troubleshooting
          1. Quick Fixes
        3. Next Steps
          1. Contributing
            1. License

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/jcr82/bruno-mcp-server'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server