burp-mcp-plus

<div align="center"> <img src="assets/logo.svg" alt="burp-mcp-plus" width="640"> <p> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a> <img src="https://img.shields.io/badge/python-3.11%2B-3776ab?logo=python&logoColor=white" alt="Python 3.11+"> <img src="https://img.shields.io/badge/MCP-1.2%2B-5e60ce" alt="MCP 1.2+"> <img src="https://img.shields.io/badge/Burp%20Suite-Pro-ff6633?logo=burpsuite&logoColor=white" alt="Burp Pro"> <img src="https://img.shields.io/badge/status-beta-orange" alt="beta"> <img src="https://img.shields.io/badge/tests-20%20passing-2ea44f" alt="tests"> </p> <p><b>The MCP for Burp Suite that doesn't make your LLM hallucinate broken HTTP requests.</b></p> </div> --- ## The problem You hook up an LLM to Burp's official MCP server and ask it to "replay this request with a tampered cookie." It dutifully crafts a Repeater payload — and silently drops the `Cookie` header, gets a 401, and confidently tells you the endpoint requires no auth. Or it forgets `Content-Length`. Or `Host`. Or uses LF instead of CRLF. Or pastes a JSON body with no headers at all. This happens because the upstream Burp MCP takes a free-form `content` string. Whatever the model emits goes straight to the wire. There's no schema, no validation, no help. The other thing that breaks long pentest sessions: **token cost**. Each `get_proxy_http_history` call ships kilobytes of repeated headers back to the model. Triage a target for an hour and you've burned a fortune re-paginating the same proxy history. --- ## What this fixes **`burp-mcp-plus`** is a Python MCP wrapper that sits between your LLM and Burp's official MCP server. Two big ideas: ### 1. Structured input, not free-form strings Every tool that touches HTTP takes typed fields — `method`, `path`, `set_headers`, `body` — and a *baseline* (a real entry from Burp's history, or a URL). The wrapper builds the wire format itself. Correct CRLF, auto-`Host`, auto-`Content-Length`, default `User-Agent`, inherited cookies. The LLM literally cannot produce a malformed request because there's no `content` parameter to put a malformed request in. ### 2. Local file ingestion for the boring stuff If you've already triaged a target with the bundled `Deduped HTTP History + JS Exporter` Burp extension, the wrapper indexes the exports on disk. `dedup_search` and `js_search` return file:line + 60-char snippets — meaningfully cheaper than re-hitting Burp every time the model wants to look at past traffic. Full content is only fetched on demand. --- ## Architecture <div align="center"> <img src="assets/architecture.svg" alt="architecture" width="720"> </div> Plain Python stdio MCP server. Talks SSE to Burp's `mcp-proxy-all` extension on `localhost:9876`. Reads dedup/JS exports off disk. Works with any MCP host: Claude Desktop, Claude Code, Cursor, Continue, anything that speaks the protocol. --- ## Features ### Live Burp interaction - **`list_history`** / **`search_history`** — paginate or regex over proxy history. Returns compact summaries (id + method + url + status), not raw bytes. - **`inspect_history_entry`** — pretty-print one entry's headers, body, target. - **`repeater_from_history`** — clone a baseline, mutate any subset of (method, path, headers, body), push to Repeater. **All other headers preserved verbatim from the baseline.** Cookies, auth tokens, Sec-Fetch-*, custom Anthropic-* / X-* headers — all carry through. - **`repeater_from_template`** — build from scratch with a URL. Optionally inherit auth from a history baseline. - **`send_request`** — same shape, but actually sends and returns the response. Skip the Repeater dance when you just want to test. - **`intruder_from_history`** — push to Intruder with `§…§` payload markers wrapped automatically around substrings you specify. - **`sitemap`** — host → method → paths tree, synthesized from history. Burp's MCP doesn't expose Target; we synthesize one. - **`collaborator_generate`** / **`collaborator_check`** — OOB canary payloads + interaction polling. ### Local dedup file ingestion Point at a `deduped_requests.txt` produced by the bundled extension and the model can search/replay endpoints from past sessions without round-tripping through Burp. - **`dedup_load`** / **`dedup_list`** — register file(s) under a name. - **`dedup_search`** — regex over `url` / `request` / `response` / `params` / `all`. Returns 60-char snippets. - **`dedup_get`** — preview by default, full request/response on demand. - **`dedup_to_repeater`** — replay a stored entry into a fresh Repeater tab with optional mutations. HTTP/2 lines auto-coerced to HTTP/1.1. ### Local JS-export ingestion Point at a `_manifest.csv` produced by the bundled extension's JS Exporter and the model can grep across all the JavaScript captured for a target. - **`js_load`** / **`js_list`** — register an export. - **`js_files`** — browse the manifest, filter by host regex. - **`js_search`** — grep across all on-disk JS. Returns file:line + snippet, max N matches per file (default 3). Transparently decodes the legacy `array('b', [...])` byte-list format that older versions of the extension produced. - **`js_read`** — fetch full content for files of interest. ### Hardened against the real world - Tolerates Burp's NDJSON-with-no-separators history format. - Recovers parse-mid-stream when Burp truncates a long response with `... (truncated)`. - `strict=False` JSON decoding for raw control bytes inside body strings. - Specific error messages for empty inputs, status markers, malformed entries — pointing the model at the next tool to call. - 20 tests covering wire-format building and edge cases (no Burp required to run them). --- ## Install ### 1. Burp side Install **MCP Server** from Burp's BApp Store. Confirm it's listening on `http://127.0.0.1:9876` (Output tab). If you want the dedup/JS ingestion features, install the bundled extension: 1. Set up Jython 2.7 in Burp → Settings → Extensions → Python environment. 2. Burp → Extensions → Installed → Add → Python → `burp-extension/deduped_history.py` from this repo. 3. Two new tabs appear: **Deduped History** and **JS Exporter**. **Before you start capturing, two things the extension needs:** - **Set your target scope.** Burp → Target → Scope → add the host(s) you're testing (e.g. `https://app.acme.com/.*`). The extension only dedupes/exports in-scope traffic, so this keeps the output clean and avoids ingesting random third-party noise (CDNs, analytics, etc.). - **Pick an output directory for the JS Exporter.** In the **JS Exporter** tab, set the output dir + project name before browsing. Files land at `<output_dir>/<project>/<host>/<flattened-path>/<file>.js` along with a `_manifest.csv` that the wrapper indexes. Then browse the target. The Deduped History tab fills as new endpoints appear; the JS Exporter tab fills as new `.js` / `.mjs` responses come through. Hit **Export** in the Deduped History tab to write `deduped_requests.txt`. ### 2. Wrapper side Requires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/). ```bash git clone https://github.com/titaniumtushar/burp-mcp-plus.git cd burp-mcp-plus uv sync uv run pytest # offline tests; no Burp required ``` ### 3. Wire it into your MCP host The configs below use four placeholders. Fill them in for your OS — quick reference at the bottom of this section. | Placeholder | What it is | | ----------- | ---------- | | `<BURP_JAVA>` | Path to the `java` binary that ships inside Burp Suite | | `<BURP_MCP_JAR>` | Path to `mcp-proxy-all.jar` (downloaded by the BApp Store extension) | | `<REPO_DIR>` | Where you cloned this repo | | `<UV>` | `"uv"` if it's on your PATH; otherwise the absolute path to the `uv` binary | #### Claude Desktop Edit your Claude Desktop config file: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux** *(unofficial builds only — Claude Desktop isn't officially distributed for Linux)*: `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "burp": { "command": "<BURP_JAVA>", "args": [ "-jar", "<BURP_MCP_JAR>", "--sse-url", "http://127.0.0.1:9876" ] }, "burp-plus": { "command": "<UV>", "args": [ "run", "--directory", "<REPO_DIR>", "burp-mcp-plus" ] } } } ``` (Sample at [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json).) Restart the host. Tools appear as `mcp__burp-plus__*`. #### Claude Code CLI Run from the repo directory (uses `$PWD` as `<REPO_DIR>`): ```bash # Add the wrapper (user scope = available in every project) claude mcp add burp-plus --scope user -- \ uv run --directory "$PWD" burp-mcp-plus # Add the upstream Burp MCP too — substitute your <BURP_JAVA> and <BURP_MCP_JAR> claude mcp add burp --scope user -- \ <BURP_JAVA> -jar <BURP_MCP_JAR> --sse-url http://127.0.0.1:9876 ``` On Windows PowerShell, replace `$PWD` with `(Get-Location).Path`. On `cmd.exe`, replace it with `%CD%`. Verify with `claude mcp list`. Tools appear in any Claude Code session as `mcp__burp-plus__*` and `mcp__burp__*`. Use `--scope project` if you want it scoped to the current repo only (writes to `.mcp.json`), or `--scope local` for just-this-machine config. #### Cursor Edit `~/.cursor/mcp.json` (global, available in every workspace) — same path on macOS / Linux / Windows (Cursor maps `~` to your home dir on every OS). Create the file if it doesn't exist: ```json { "mcpServers": { "burp": { "command": "<BURP_JAVA>", "args": [ "-jar", "<BURP_MCP_JAR>", "--sse-url", "http://127.0.0.1:9876" ] }, "burp-plus": { "command": "<UV>", "args": [ "run", "--directory", "<REPO_DIR>", "burp-mcp-plus" ] } } } ``` Then: Cursor → **Settings** → **MCP** → toggle both servers on. The status dot should go green; if it stays red, click **View logs** in the same panel to see why. Use `.cursor/mcp.json` in a workspace root instead of `~/.cursor/mcp.json` if you want it scoped to one project. #### Continue / Cline / other stdio MCP hosts Same JSON shape, host-specific config path. The wrapper itself doesn't care which host launches it — all it needs is a stdio pipe. --- #### Where the placeholders live on each OS **`<BURP_JAVA>`** — the JRE bundled inside Burp: | OS | Typical path | | -- | ------------ | | macOS | `/Applications/Burp Suite Professional.app/Contents/Resources/jre.bundle/Contents/Home/bin/java` | | Linux | `~/BurpSuitePro/jre/bin/java` *(or wherever you extracted Burp's installer)* | | Windows | `C:\Users\<you>\AppData\Local\Programs\BurpSuitePro\jre\bin\java.exe` | **`<BURP_MCP_JAR>`** — downloaded by Burp's BApp Store when you install the MCP Server extension: | OS | Typical path | | -- | ------------ | | macOS / Linux | `~/.BurpSuite/bapps/<extension-id>/burp-mcp-all.jar` *(or `~/.BurpSuite/mcp-proxy/mcp-proxy-all.jar` depending on Burp version)* | | Windows | `C:\Users\<you>\AppData\Roaming\BurpSuite\bapps\<extension-id>\burp-mcp-all.jar` | To find the exact path on your machine: `find ~/.BurpSuite -name "*.jar"` (macOS / Linux) or look in `%APPDATA%\BurpSuite\bapps\` (Windows). **`<REPO_DIR>`** — wherever you ran `git clone`. Get it with `pwd` (POSIX shells) or `cd` (Windows `cmd`). **`<UV>`** — most users can just use `"uv"` (the literal string) and let the system PATH resolve it. If your MCP host can't find `uv` that way, use the absolute path: | Install method | Typical path | | -------------- | ------------ | | macOS Homebrew (Apple Silicon) | `/opt/homebrew/bin/uv` | | macOS Homebrew (Intel) | `/usr/local/bin/uv` | | Linux / `curl` install | `~/.local/bin/uv` | | Windows | `%USERPROFILE%\.local\bin\uv.exe` | | `pipx install uv` (any OS) | check `pipx environment` | To find it: `which uv` (POSIX) or `where uv` (Windows). --- ## The bundled Burp extension `burp-extension/deduped_history.py` is a Jython extension that produces the dedup/JS exports the wrapper indexes. **Tab 1: Deduped History.** Watches proxy traffic. Adds a row only when a new (method, host, path, parameters) tuple appears. Re-fires when new query/body parameter names show up on an endpoint. Export the whole thing to `deduped_requests.txt`. **Tab 2: JS Exporter.** Watches for JavaScript responses, saves each unique JS file to `<output>/<project>/<host>/<flattened-path>/<name>.js`, writes a `_manifest.csv`. Detects version strings from filenames and content hashes. --- ## Token economics Rough numbers from a typical pentest session: | Action | Upstream Burp MCP | burp-mcp-plus | Reduction | | ------ | ---------------- | -------------- | --------- | | List 50 history entries | ~60 KB | ~3 KB | 95% | | Search history (regex, 30 hits) | ~90 KB | ~4 KB | 95% | | Replay one auth'd request | ~5 KB request + ~5 KB confirmation | ~1 KB | 80% | | Find an endpoint in past triage | re-paginate proxy (~60 KB) | dedup_search (~600 B) | 99% | | Grep all JS for a pattern | not feasible | ~2 KB w/ snippets | — | The wrapper's job is to keep the model focused on the smallest bytes that answer the question. --- ## Tested with - Burp Suite Pro 2025.x - Anthropic MCP Server BApp 1.x - Claude Desktop on macOS - Python 3.11, 3.12, 3.13 - macOS arm64, Linux x86_64 Should work on Windows but I haven't tested it. Reports welcome. --- ## Security notes This is a **defensive tool for authorized testing.** It's no more dangerous than Burp itself — but: - The MCP exposes your Burp's full power to whatever model you connect. Don't connect untrusted models. - File ingestion (`dedup_*`, `js_*`) reads paths you provide. There's no sandbox; treat the wrapper's host as trusted. - The wrapper doesn't authenticate to Burp's MCP — it relies on Burp's `localhost`-only binding. Don't expose Burp's MCP port externally. - Pentest scope discipline applies. The wrapper makes it easier to fire requests; it doesn't validate that you should. --- ## Contributing Issues and PRs welcome. A few ground rules: - **Tests stay green.** `uv run pytest` before opening a PR. The builder in `src/burp_mcp_plus/builder.py` is pure logic and easy to test offline. - **No new free-form `content` parameters.** That's the whole anti-pattern this tool exists to prevent. Add structured fields instead. - **Compact returns.** If a new tool would return more than a few KB by default, add a `limit` / `field` / `preview` knob. - **No hidden network calls.** Tool side effects should be obvious from the name. --- ## License [MIT](LICENSE). ## Thanks - **PortSwigger** — Burp Suite and the official MCP server. - **Anthropic** — the MCP spec and Python SDK. - Everyone running long pentest sessions who got tired of debugging "why did my LLM drop the Cookie header again."