# How to Set Up and Use the BurpSuite MCP Server with 78 Available Tools: A Complete Guide

> Master the BurpSuite MCP server and its 78 tools. This guide shows you how to set up and use this powerful extension for AI-driven penetration testing automation.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-07

---

**The BurpSuite MCP server is a Java-based Burp Suite extension that exposes 78 native penetration testing tools through a Node.js bridge, enabling AI-driven automation of proxy analysis, intruder attacks, and scanner audits via the reverse-skill framework.**

The BurpSuite MCP (Montoya Control Protocol) server bundled with `zhaoxuya520/reverse-skill` transforms Burp Suite Professional and Community editions into a programmable security automation platform. This extension translates JSON commands from AI prompts into native Burp API calls, giving you full-stack control over proxy history, scanner configurations, and collaborator interactions without manual GUI manipulation.

## Architecture Overview

The BurpSuite MCP server operates as a dual-component system that bridges the gap between AI prompt interfaces and Burp Suite's internal Montoya API.

**Component Breakdown:**

- **`burp-mcp-full` project** – A Java extension that runs inside Burp Suite's JVM and exposes internal functionality via local HTTP endpoints.

- **[`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js)** – A Node.js script located at [`burp-mcp-full/mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burp-mcp-full/mcp-bridge.js) that receives JSON commands from the reverse-skill AI runtime and forwards them to the Java extension. The bridge configuration passes this path to the MCP JSON definition as `"args": ["<SKILL_ROOT>/burp-mcp-full/mcp-bridge.js"]`.

- **[`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh)** – The helper script at [`skills/scripts/bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/scripts/bootstrap-reverse.sh) contains the `ensure_burpsuite_mcp()` function (lines 614-622) that automates JAR compilation, generates MCP server definitions, and registers the server under the key `burpsuite`.

- **AI Tool Registry** – The [`burpsuite-mcp-guide.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burpsuite-mcp-guide.md) file documents all 78 available tools, including 63 atomic operations and 7 composite scenarios covering proxy history analysis, intruder automation, and collaborator polling.

Once registered, the AI communicates with Burp Suite via `http://localhost:9876/mcp`, routing any prompt referencing the `burpsuite` capability to the appropriate internal API method.

## Prerequisites

Before building the extension, ensure your environment meets these requirements across Windows, macOS, or Linux:

- **Burp Suite** – Professional or Community edition installed from the official PortSwigger repository.
- **Java Development Kit** – Version 11 or higher for compiling the extension and running Burp.
- **Node.js** – Version 14 or higher to execute the bridge script.
- **Gradle** – Used by the build script to package the Java extension.

**Platform-Specific Installation:**

```bash

# macOS (using Homebrew)

brew install --cask burp-suite
brew install node openjdk

# Linux/Kali

sudo apt install burpsuite nodejs npm openjdk-11-jdk

# Windows

# Download Burp Suite installer from portswigger.net

# Install Node via chocolatey: choco install nodejs

```

## Step 1: Build the MCP Extension

Clone the reverse-skill repository and compile the Java extension using the provided Gradle wrapper.

```bash
git clone https://github.com/zhaoxuya520/reverse-skill.git
cd reverse-skill/burp-mcp-full
chmod +x build.sh
./build.sh

```

The [`build.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/build.sh) script compiles the Montoya API integration and outputs the extension JAR to `build/libs/burp-mcp-full.jar`. Verify the build succeeded:

```bash
ls -la build/libs/burp-mcp-full.jar

```

This JAR file contains the server implementation that exposes Burp's internal functionality to the Node bridge.

## Step 2: Load the Extension in Burp Suite

Start Burp Suite and load the compiled extension through the Extensions interface:

1. Launch Burp Suite Professional or Community.
2. Navigate to **Extensions → Installed**.
3. Click **Add**, select **Java** as the extension type.
4. Browse to `burp-mcp-full/build/libs/burp-mcp-full.jar` in your reverse-skill directory.
5. Click **Next** to load the extension.

The extension appears as **burp-mcp-full** in the loaded extensions list. Once active, it opens port 9876 to accept MCP commands from the bridge.

## Step 3: Register with reverse-skill

Run the bootstrap script from the repository root to generate the bridge configuration and register the server:

```bash
cd reverse-skill
bash skills/scripts/bootstrap-reverse.sh burpsuite-mcp

```

The `ensure_burpsuite_mcp()` function performs three critical operations:

1. Generates JSON configuration pointing to [`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js).
2. Calls `write_mcp_server "burpsuite" "$bridge_json"` to store the definition.
3. Outputs a manual installation reminder if the JAR is not detected.

After successful registration, the AI runtime recognizes `burpsuite` as a valid MCP server and routes compatible prompts to `http://localhost:9876/mcp`.

## Step 4: Invoke the 78 Tools via AI

With the server registered, reference any of the 78 capabilities documented in [`skills/pentest-tools/references/burpsuite-mcp-guide.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/references/burpsuite-mcp-guide.md) using natural language prompts or direct tool invocations.

**Example prompt for proxy history analysis:**

```text
Analyze the captured traffic in Burp's proxy history for suspicious parameters, highlight potential injection points, and generate a concise report.

```

The AI translates this into MCP calls such as `burp_proxy_history` and `burp_scanner_audit`, executing the corresponding Burp API methods and returning structured results. The guide categorizes tools into atomic operations (e.g., `burp_intruder_attack`, `burp_collaborator_poll`) and composite scenarios for common workflows like automated brute-force attacks.

## Troubleshooting Common Issues

| Symptom | Cause | Solution |
|---------|-------|----------|
| `MANUAL_INSTALL_REQUIRED` error | JAR file missing or path incorrect | Re-run [`./build.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/./build.sh) in `burp-mcp-full/` and verify `build/libs/burp-mcp-full.jar` exists. |
| Port 9876 already in use | Another process occupies the MCP endpoint | Identify the process with `lsof -i:9876` (Linux/macOS) or `netstat -ano \| findstr 9876` (Windows) and terminate it, or modify the port in [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh). |
| Extension fails to load (class not found) | Burp Suite version incompatibility (≥2025.5) | Update API calls in [`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js) to use current Montoya API signatures as documented in [`skills/field-journal/2026-06-29_burp-mcp-full-test-and-fix.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/2026-06-29_burp-mcp-full-test-and-fix.md). |
| AI returns "tool not found" | Incorrect tool name in prompt | Consult [`burpsuite-mcp-guide.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burpsuite-mcp-guide.md) (lines 315-330) for exact atom names like `burp_proxy_history` versus `proxy_history`. |

## Quick Reference Commands

| Task | Command |
|------|---------|
| Build extension | `cd burp-mcp-full && ./build.sh` |
| Start Burp (CLI) | `java -jar burpsuite_pro.jar` |
| Register MCP server | `bash skills/scripts/bootstrap-reverse.sh burpsuite-mcp` |
| Verify server status | `curl http://localhost:9876/mcp/status` |
| Reload after changes | Extensions → burp-mcp-full → Unload → Add (rebuilt JAR) |

## Summary

- **The BurpSuite MCP server** consists of a Java extension (`burp-mcp-full.jar`) and a Node bridge ([`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js)) that exposes 78 Burp Suite tools to AI systems.
- **Build process** requires Java 11+, Node 14+, and Gradle to compile the Montoya API integration.
- **Registration** via [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh) creates the `burpsuite` MCP entry and configures the local endpoint at port 9876.
- **Usage** involves loading the JAR into Burp Suite, running the bootstrap script, and referencing tool names from [`burpsuite-mcp-guide.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/burpsuite-mcp-guide.md) in AI prompts.
- **Troubleshooting** focuses on JAR verification, port conflicts, and API compatibility with recent Burp Suite versions.

## Frequently Asked Questions

### What are the 78 tools available in the BurpSuite MCP server?

The 78 capabilities consist of 63 atomic tools and 7 composite scenarios covering proxy history manipulation (`burp_proxy_history`), automated intruder attacks (`burp_intruder_attack`), active scanning (`burp_scanner_audit`), collaborator client operations (`burp_collaborator_poll`), site map enumeration, repeater modifications, and extension management. The complete enumeration resides in [`skills/pentest-tools/references/burpsuite-mcp-guide.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/pentest-tools/references/burpsuite-mcp-guide.md).

### Can I use the MCP server with Burp Suite Community Edition?

Yes, the extension supports both Professional and Community editions. However, certain tools like the automated scanner and specific intruder attack configurations require Professional features to function fully. The bridge itself and basic proxy history operations work in Community Edition.

### How do I update the MCP server after Burp Suite updates?

When Burp Suite updates (particularly to versions ≥2025.5), Montoya API signatures may change. Update the [`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js) references to use current API methods like `api.burpSuite().buildNumber()`, then rebuild the JAR using [`./build.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/./build.sh) and reload the extension in Burp. Check [`skills/field-journal/2026-06-29_burp-mcp-full-test-and-fix.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/field-journal/2026-06-29_burp-mcp-full-test-and-fix.md) for documented API migrations.

### Why does the bootstrap script report "MANUAL_INSTALL_REQUIRED"?

This occurs when the `ensure_burpsuite_mcp()` function cannot locate `build/libs/burp-mcp-full.jar`. Confirm the build completed successfully, verify the file exists in the `burp-mcp-full` directory, and ensure you run [`bootstrap-reverse.sh`](https://github.com/zhaoxuya520/reverse-skill/blob/main/bootstrap-reverse.sh) from the repository root so path resolution functions correctly.