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

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

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

Contributing

Contributions welcome! Please submit issues or pull requests.

License

MIT Juan Ruiz

服务配置

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

来源

来源：github
链接：https://github.com/jcr82/bruno-mcp-server

bruno-mcp-server