Bruno

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 in

---

README truncated. View full README on GitHub.