Bruno MCP Server

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

1. Install the package globally:

npm install -g bruno-mcp-server

2. 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"]
    }
  }
}

3. 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

1. Verify installation: cat ~/.claude.json (or project's .claude.json if using --scope project)
2. Restart Claude Desktop/CLI after installation
3. 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

Collection Not Found

• Use absolute paths
• Verify bruno.json exists in collection directory
• Check file permissions

Permission Issues

• Ensure read access to Bruno collections
• Verify server can execute Bruno CLI

Documentation

• Getting Started Guide
• Configuration Reference
• Usage Patterns
• Troubleshooting Guide
• CI/CD Integration
• MCP Tools API Reference

Contributing

Contributions welcome! Please submit issues or pull requests.

License

MIT © Juan Ruiz

Links

• GitHub Repository
• Issue Tracker
• Bruno CLI Documentation
• Model Context Protocol