# How to Set Up Burp Suite MCP for 78-Tool AI-Controlled Web Security Testing in reverse-skill > Learn how to set up Burp Suite MCP in the reverse-skill repository for AI-controlled web security testing with 78 tools. Integrate with MCP AI clients effortlessly. - Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill) - Tags: how-to-guide - Published: 2026-08-14 --- **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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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: ```powershell cd burp-mcp-full .\build.bat ``` On Linux or macOS: ```bash 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 `/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: ```bash curl http://127.0.0.1:9876/health ``` Expected response: ```json {"status":"ok","tools":["proxy_history","intruder_attack_async","collaborator_generate",...]} ``` ## Step 3: Configure the MCP Bridge in Your AI Client The [`mcp-bridge.js`](https://github.com/zhaoxuya520/reverse-skill/blob/main/mcp-bridge.js) file implements the stdio-server specification from `reverse-skill`. Add this configuration to your AI client's MCP settings: ```json { "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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/.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: ```json { "method": "tools/list", "id": 1, "params": {} } ``` The `fetchTools` implementation queries `http://127.0.0.1:9876/tools` and returns structured metadata: ```json { "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_` naming convention mapped from Burp's internal API surface. ## Common Operations with Burp Suite MCP ### Retrieve Recent Proxy Traffic ```json { "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 ```json { "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 ```json { "method": "tools/call", "id": 4, "params": { "name": "burp_collaborator_generate", "arguments": { "count": 5 } } } ``` Then poll for callbacks: ```json { "method": "tools/call", "id": 5, "params": { "name": "burp_collaborator_poll", "arguments": { "timeout_seconds": 30 } } } ``` ### Register Custom HTTP Handler ```json { "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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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_` with JSON-RPC `tools/call` method - **Reference**: Full documentation lives 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) ## 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.