How to Set Up Burp Suite MCP for 78-Tool AI-Controlled Web Security Testing in reverse-skill

The reverse-skill repository provides a complete Burp Suite MCP implementation that exposes 78 security testing tools to any Model Context Protocol (MCP) compatible AI client through a Java extension and Node.js bridge architecture.

This guide walks through configuring the three-component system—Burp MCP Extension, STDIO Bridge, and AI client—so you can control Burp Suite programmatically from Claude, Kiro, Cursor, and other MCP-enabled interfaces. All components ship with the zhaoxuya520/reverse-skill repository.

Architecture Overview

The Burp Suite MCP integration consists of three tightly-coupled layers:

Component	Technology	Function	Key File
Burp MCP Extension	Java	Embedded HTTP server on 127.0.0.1:9876 bridging MCP calls to Burp's native APIs	burp-mcp-full/build/libs/burp-mcp-full.jar
STDIO Bridge	Node.js	Translates MCP JSON-RPC 2.0 stdio protocol to HTTP requests; discovers tools at runtime	burp-mcp-full/mcp-bridge.js
AI Client Config	JSON	Registers the bridge command under mcpServers.burpsuite	Client-specific settings file

When an AI client invokes burp_proxy_history, the callTool function (lines 90-117 in mcp-bridge.js) maps the method name to GET /proxy_history and forwards the payload. The fetchTools function (lines 42-60) populates the 78-tool catalog at initialization.

Prerequisites

Before setup, verify you have:

• Burp Suite Professional — required for full API access; Community Edition lacks the Montoya API hooks
• Java JDK 11+ — for compiling the extension
• Node.js 16+ — for running the bridge
• MCP-compatible AI client — Claude Code, Kiro, Cursor, or custom implementation

Step 1: Build the Java MCP Extension

The extension must be compiled from source. The repository includes platform-specific build scripts.

On Windows:

cd burp-mcp-full
.\build.bat

On Linux or macOS:

cd burp-mcp-full
chmod +x build.sh
./build.sh

The Gradle build (defined in burp-mcp-full/build.gradle and burp-mcp-full/settings.gradle) produces burp-mcp-full/build/libs/burp-mcp-full.jar.

Step 2: Load the Extension in Burp Suite

1. Launch Burp Suite Professional
2. Navigate to Extensions → Installed → Add
3. Select Java as the extension type
4. Browse to <SKILL_ROOT>/burp-mcp-full/build/libs/burp-mcp-full.jar

Successful initialization displays: [MCP] Server started on http://127.0.0.1:9876 in the Output tab.

Verify the endpoint responds:

curl http://127.0.0.1:9876/health

Expected response:

{"status":"ok","tools":["proxy_history","intruder_attack_async","collaborator_generate",...]}

Step 3: Configure the MCP Bridge in Your AI Client

The mcp-bridge.js file implements the stdio-server specification from reverse-skill. Add this configuration to your AI client's MCP settings:

{
  "mcpServers": {
    "burpsuite": {
      "command": "node",
      "args": [
        "/absolute/path/to/reverse-skill/burp-mcp-full/mcp-bridge.js"
      ]
    }
  }
}

Critical: Use absolute paths. Relative paths fail when the AI client launches from a different working directory.

Client-Specific Locations

• Claude Code: ~/.claude-mcp.json or project-level .claude-mcp.json
• Kiro: ~/.config/kiro/mcp.json
• Cursor: Settings → AI → MCP Servers

Restart the AI client to establish the connection. The bridge logs initialization messages to stderr; check these if tools don't appear.

Step 4: Verify 78-Tool Availability

Once connected, request the tool catalog:

{
  "method": "tools/list",
  "id": 1,
  "params": {}
}

The fetchTools implementation queries http://127.0.0.1:9876/tools and returns structured metadata:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "burp_proxy_history",
        "description": "Retrieve HTTP/S request/response pairs from Burp's proxy history"
      },
      {
        "name": "burp_intruder_attack_async",
        "description": "Execute multi-threaded payload-based attacks with custom positions"
      },
      {
        "name": "burp_collaborator_generate",
        "description": "Create Burp Collaborator payloads for out-of-band detection"
      }
    ]
  }
}

All 78 tools follow the burp_<toolname> naming convention mapped from Burp's internal API surface.

Common Operations with Burp Suite MCP

Retrieve Recent Proxy Traffic

{
  "method": "tools/call",
  "id": 2,
  "params": {
    "name": "burp_proxy_history",
    "arguments": {
      "limit": 50,
      "filter": "https://target.com"
    }
  }
}

Returns serialized proxy entries with request/response bodies (subject to Burp's display limits).

Execute Asynchronous Intruder Attack

{
  "method": "tools/call",
  "id": 3,
  "params": {
    "name": "burp_intruder_attack_async",
    "arguments": {
      "url_template": "https://api.target.com/v1/users/@@/profile",
      "from": 1000,
      "to": 9999,
      "pad_digits": 4,
      "method": "GET",
      "threads": 20,
      "success_length_not": 342
    }
  }
}

The @@ marker indicates payload positions. Results include response codes, lengths, and timing for correlation.

Generate and Poll Collaborator Interactions

{
  "method": "tools/call",
  "id": 4,
  "params": {
    "name": "burp_collaborator_generate",
    "arguments": { "count": 5 }
  }
}

Then poll for callbacks:

{
  "method": "tools/call",
  "id": 5,
  "params": {
    "name": "burp_collaborator_poll",
    "arguments": { "timeout_seconds": 30 }
  }
}

Register Custom HTTP Handler

{
  "method": "tools/call",
  "id": 6,
  "params": {
    "name": "burp_register_http_handler",
    "arguments": {
      "match_condition": "Host contains: target.com",
      "action": "Add header",
      "header_name": "X-Bug-Bounty",
      "header_value": "researcher@example.com"
    }
  }
}

Handlers persist until Burp restarts or burp_unregister_http_handler is called.

Troubleshooting Common Issues

Bridge Reports "Connection Refused"

The disconnectedResponse handler (lines 124-130 in mcp-bridge.js) emits this when 127.0.0.1:9876 is unreachable:

1. Verify Burp is running and the extension loaded successfully
2. Check for port conflicts: netstat -an | findstr 9876 (Windows) or lsof -i :9876 (Unix)
3. Confirm no firewall rules block localhost loopback

Tools List Empty or Stale

The bridge caches tool definitions at startup. If Burp's tool set changes:

1. Restart the bridge process (AI client typically handles this)
2. Or send explicit initialize request to trigger fetchTools re-execution

Gradle Build Failures

Ensure JAVA_HOME points to a JDK (not JRE) and the gradlew wrapper has execute permissions. The build.gradle depends on Burp's Montoya API from Maven Central.

Advanced Configuration

Custom Bridge Port

Modify MCP_SERVER_PORT in the Java extension's source before building, or use environment variable injection in mcp-bridge.js (custom modification required).

Extending Tool Coverage

The 78-tool set reflects Burp's current API bindings in burp-mcp-full/src/main/java/. To expose additional Burp capabilities, extend the Java handler classes and rebuild.

Summary

• Compiling: Use build.bat (Windows) or build.sh (Linux/macOS) to create burp-mcp-full.jar
• Loading: Install the JAR via Burp's Extensions tab; confirm 127.0.0.1:9876 responds
• Bridging: Configure AI client to execute node burp-mcp-full/mcp-bridge.js via MCP settings
• Operating: Invoke any of 78 tools as burp_<toolname> with JSON-RPC tools/call method
• Reference: Full documentation lives in skills/pentest-tools/references/burpsuite-mcp-guide.md

Frequently Asked Questions

What MCP clients work with reverse-skill's Burp Suite integration?

Any client implementing the Model Context Protocol specification works. Verified compatible clients include Claude Code, Kiro, Cursor, and OpenAI's Agents SDK. The bridge uses standard JSON-RPC 2.0 over stdio, requiring no client-specific modifications.

Can I use Burp Suite Community Edition?

No. The MCP extension relies on the Montoya API available only in Burp Suite Professional. Community Edition lacks programmatic access to proxy history, Intruder, Scanner, and other features required for the 78-tool integration. License validation occurs at runtime in the Java extension.

How do I add custom tools beyond the built-in 78?

Extend the Java source in burp-mcp-full/src/main/java/ to expose additional Burp API methods. Add handler classes implementing the ToolHandler interface, register them in McpServer.java, and rebuild with Gradle. The bridge automatically discovers new endpoints via the /tools endpoint.

Where are the complete usage examples and prompt templates?

The skills/pentest-tools/references/burpsuite-mcp-guide.md file contains comprehensive AI prompt examples, tool parameter schemas, and workflow automation patterns. Lines 997-1009 specifically address installation troubleshooting, while earlier sections demonstrate multi-step penetration testing workflows combining multiple Burp tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}