Bruno API MCP server

This server enables interaction with Bruno API collections through the Model Context Protocol (MCP), making your API collections accessible to AI agents and other MCP clients. It transforms Bruno API collections into MCP tools, allowing for seamless integration of APIs without additional custom development.

Installation

To get started with the Bruno API MCP Server:

npm install

Running the Server

Start the server by pointing it to your Bruno API collection:

node --loader ts-node/esm src/index.ts --bruno-path /path/to/bruno/collection

Command-line Options

• --bruno-path or -b: Path to your Bruno API collection directory (required)
• --environment or -e: Name of the environment to use
• --include-tools: Comma-separated list of specific tools to include
• --exclude-tools: Comma-separated list of tools to exclude

You can format these options in two ways:

--include-tools tool1,tool2,tool3    # Space-separated format
--include-tools=tool1,tool2,tool3    # Equals-sign format

Predefined Script Shortcuts

For convenience, you can use these npm scripts:

# Start with default settings
npm start

# Start with CFI API path
npm run start:cfi

# Start with local environment
npm run start:local

# Start with only specific tools included
npm run start:include-tools

# Start with specific tools excluded
npm run start:exclude-tools

Connecting to the Server

You can connect to the server from clients using:

• Local connection: http://localhost:8000/sse
• From Windows to WSL: http://<WSL_IP>:8000/sse
  • Get your WSL IP with: hostname -I | awk '{print $1}'

Debugging

Enable detailed logging using the debug library:

# Debug everything
DEBUG=* npm start

# Debug specific components
DEBUG=bruno-parser npm start    # Debug Bruno parser operations
DEBUG=bruno-request npm start   # Debug request execution
DEBUG=bruno-tools npm start     # Debug tool creation and registration

# Debug multiple components
DEBUG=bruno-parser,bruno-request npm start

On Windows:

# CMD
set DEBUG=bruno-parser,bruno-request && npm start

# PowerShell
$env:DEBUG='bruno-parser,bruno-request'; npm start

Available Tools

List Environments

Lists all available environments in your Bruno API collection:

• No parameters required
• Returns available environments and the currently active one

Echo

Simple testing tool that echoes back a message:

• Parameter: message (string)

Using Custom Parameters with Tools

Environment Override

Specify a different environment for a specific request:

{
  "environment": "us-dev"
}

Variable Replacements

Override specific variables for a single request:

{
  "variables": {
    "dealId": "abc123",
    "customerId": "xyz789",
    "apiKey": "your-api-key"
  }
}

Query Parameters

Add or override query parameters:

{
  "query": {
    "limit": "10",
    "offset": "20",
    "search": "keyword"
  }
}

Custom Body Parameters

Provide custom parameters in the request body:

{
  "body": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

Complete Example

A complete example combining all customization types:

{
  "environment": "staging",
  "variables": {
    "dealId": "abc123",
    "apiKey": "test-key-staging"
  },
  "query": {
    "limit": "5",
    "sort": "created_at"
  },
  "body": {
    "status": "approved",
    "amount": 5000
  }
}

Bruno API Collection Structure

Your Bruno API collection should follow this structure:

collection/
├── collection.bru       # Collection settings
├── environments/        # Environment configurations
│   ├── local.bru
│   └── remote.bru
└── requests/            # API requests
    ├── request1.bru
    └── request2.bru

Each request is automatically converted into an MCP tool, making it available through the MCP protocol.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.