Bruno MCP Server

Tests Coverage TypeScript License

A Model Context Protocol (MCP) server that integrates Bruno CLI for API testing and collection management. Execute API tests, validate collections, and generate reports through the Model Context Protocol.

Features

🚀 Run API Tests - Execute individual requests or entire collections
🔍 Request Introspection - Inspect request details without execution
✅ Validation - Validate collections and environments
📊 Report Generation - JSON, JUnit XML, and HTML reports
🌍 Environment Management - List, validate, and switch environments
🔎 Collection Discovery - Recursive search for Bruno collections
🧪 Dry Run Mode - Validate without making HTTP calls
🔒 Security - Path validation, input sanitization, secret masking
⚡ Performance - Request caching and execution metrics
🏥 Health Monitoring - Server health checks with detailed diagnostics

Quick Start

Prerequisites

Node.js 20 or higher
Bruno collections (.bru files)

📝 What is Bruno MCP Server?

The Bruno MCP Server integrates the Bruno CLI (an open-source API client) with the Model Context Protocol (MCP) to enable direct API testing, collection management, and reporting via Claude.

Bruno stores its collections as human-readable .bru files in your filesystem, allowing for seamless integration with version control (Git).

🚀 Key Capabilities

API Execution - Run individual requests or full test collections
Validation - Perform schema and environment validation (including a dry run mode without making HTTP calls)
Discovery - Recursively locate Bruno collections across specified directories
Environment Management - List and validate specific environments within a collection (e.g., dev, staging, production)
Reporting - Generate comprehensive reports in JSON, JUnit XML, or HTML formats

💡 Sample Prompts

Goal	Sample Prompt
Discovery	"Find all Bruno collections in my projects directory at `/Users/user-name/projects` "
Request Execution	"Run the 'Get User' request from `/path/to/collection` using the 'dev' environment"
Validation (Dry Run)	"Validate the 'Create User' request from `/path/to/collection` without making the HTTP call"
Full Run & Reporting	"Run all tests in my API collection at `/path/to/collection` and generate HTML and JSON reports in `./reports` "
Environment Check	"List all environments in `/path/to/collection` and validate the 'production' environment"

📥 Installation (Claude CLI)

Option 1: Using Claude MCP Add (Recommended)

The simplest method is using the claude mcp add command, which automatically installs the server and configures the MCP transport.

Scope

Command

Global

(personal use)

claude mcp add --transport stdio bruno -- npx -y bruno-mcp-server

Project-Scoped

(team projects)

claude mcp add --transport stdio bruno --scope project -- npx -y bruno-mcp-server

Note: The --transport stdio flag and the -- separator are required. The -y flag automatically accepts npx prompts.

Option 2: Manual Installation

Install the package globally:

npm install -g bruno-mcp-server

Add to your Claude CLI configuration file:
- Global config: ~/.claude.json
- Project config: .claude.json (in your project root)

{ "mcpServers": { "bruno": { "command": "npx", "args": ["bruno-mcp-server"] } } }

Restart your Claude CLI session

✅ Verification

To confirm the server is installed correctly, check the appropriate configuration file:

# For global installation cat ~/.claude.json # For project-scoped installation cat .claude.json

You should see the "bruno" server listed under mcpServers.

Test the installation by starting a new Claude CLI session and trying:

"Check if the bruno MCP server is available and list its tools"

Available Tools

1. `bruno_run_request` - Execute a Single Request

bruno_run_request({ collectionPath: "/path/to/collection", requestName: "Get User", environment: "dev", // optional envVariables: { // optional "API_KEY": "your-key" }, reporterJson: "./report.json", // optional reporterJunit: "./report.xml", // optional reporterHtml: "./report.html", // optional dryRun: false // optional - validate only })

2. `bruno_run_collection` - Execute a Collection

bruno_run_collection({ collectionPath: "/path/to/collection", environment: "dev", // optional folderPath: "auth", // optional - run specific folder envVariables: { }, // optional reporterJson: "./report.json", // optional dryRun: false // optional })

3. `bruno_list_requests` - List All Requests

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

4. `bruno_discover_collections` - Find Collections

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

5. `bruno_list_environments` - List Environments

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

6. `bruno_validate_environment` - Validate Environment

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

7. `bruno_get_request_details` - Inspect Request

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

8. `bruno_validate_collection` - Validate Collection

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

9. `bruno_health_check` - Health Diagnostics

bruno_health_check({ includeMetrics: true, // optional includeCacheStats: true // optional })

Dry Run Mode

Validate request configuration without executing HTTP calls:

bruno_run_request({ collectionPath: "/path/to/collection", requestName: "Create User", dryRun: true })

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.

Report Generation

Generate test reports in multiple formats:

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

JSON: Detailed results for programmatic processing
JUnit XML: CI/CD integration (Jenkins, GitHub Actions, GitLab CI)
HTML: Interactive report with Vue.js interface

Configuration

Create bruno-mcp.config.json in your project root or home directory:

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

See bruno-mcp.config.example.json for all options.

Development

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

Project Structure

bruno-mcp-server/ ├── src/ │ ├── index.ts # Main MCP server │ ├── bruno-cli.ts # Bruno CLI wrapper │ ├── config.ts # Configuration management │ ├── security.ts # Security utilities │ ├── performance.ts # Caching and metrics │ ├── logger.ts # Logging system │ ├── di/ # Dependency injection │ ├── services/ # Business logic services │ ├── tools/ │ │ ├── handlers/ # MCP tool handlers (9 tools) │ │ └── formatters/ # Output formatters │ └── __tests__/ # Test suites │ ├── unit/ # Unit tests (100% handler coverage) │ ├── integration/ # Integration tests │ └── e2e/ # End-to-end workflow tests ├── dist/ # Compiled output └── bruno-mcp.config.json # Configuration file

Test Coverage

Overall Coverage: 91.04%
Handler Coverage: 99.72% (9/9 handlers)
Formatter Coverage: 98.74%
Total Tests: 362 passing
Test Types: Unit, Integration, E2E

Security Features

Path Validation: Prevents directory traversal attacks
Input Sanitization: Protects against command injection
Secret Masking: Automatically masks sensitive data in logs
Environment Validation: Validates variables for safe characters

Troubleshooting

Installation Issues

Error: "missing required argument 'commandOrUrl'"

Make sure you include --transport stdio and -- separator
Correct: claude mcp add --transport stdio bruno -- npx -y bruno-mcp-server
Wrong: claude mcp add bruno-mcp-server

MCP Server Not Showing Up in Claude

Verify installation: cat ~/.claude.json (or project's .claude.json if using --scope project)
Restart Claude Desktop/CLI after installation
Check the server is configured correctly in the JSON file

npx Prompts During Installation

Always use the -y flag: npx -y bruno-mcp-server
This auto-accepts installation prompts

Bruno CLI Not Found

# Verify Bruno CLI installation npx bru --version # Server uses local installation in node_modules/.bin/bru

Bruno MCP Server

Features

Quick Start

Prerequisites

📝 What is Bruno MCP Server?

🚀 Key Capabilities

💡 Sample Prompts

📥 Installation (Claude CLI)

Option 1: Using Claude MCP Add (Recommended)

Option 2: Manual Installation

✅ Verification

Available Tools

1. bruno_run_request - Execute a Single Request

2. bruno_run_collection - Execute a Collection

3. bruno_list_requests - List All Requests

4. bruno_discover_collections - Find Collections

5. bruno_list_environments - List Environments

6. bruno_validate_environment - Validate Environment

7. bruno_get_request_details - Inspect Request

8. bruno_validate_collection - Validate Collection

9. bruno_health_check - Health Diagnostics

Dry Run Mode

Report Generation

Configuration

Development

Project Structure

Test Coverage

Security Features

Troubleshooting

Installation Issues

Bruno CLI Not Found

Collection Not Found

Permission Issues

Documentation

Contributing

License

Links

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API