Skip to content
Back to search

BurpMCP-Ultra

AI-powered MCP server for Burp Suite Professional — 149 tools across proxy, scanner, inline fuzzer, race conditions, guided injection, JWT/IDOR attacks, recon & OOB, with a real-time dashboard and hardened localhost security. Drive Burp from Claude Code or any MCP client.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cy-s3c--burpmcp-ultra/badge.svg)](/listings/cy-s3c--burpmcp-ultra)

HTML

<a href="/listings/cy-s3c--burpmcp-ultra"><img src="/api/listings/cy-s3c--burpmcp-ultra/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Build

git clone https://github.com/Cy-S3c/BurpMCP-Ultra.git
cd BurpMCP-Ultra
./gradlew shadowJar

Output: `build/libs/burpmcp-ultra-2.3.1.jar` (~13 MB). A **JDK 17–21** must be installed — see [Building from Source](#building-from-source). Pre-built JARs are on the [Releases](https://github.com/Cy-S3c/BurpMCP-Ultra/releases) page.

2. Load into Burp

1. Burp Suite Pro → **Extensions** → **Add** 2. Select the JAR 3. The **BurpMCP-Ultra** tab appears with a green "Running" status and your connection token

3. Connect Claude Code

{
  "mcpServers": {
    "burp": {
      "type": "sse",
      "url": "http://127.0.0.1:9876/",
      "headers": {
        "Authorization": "Bearer PASTE_TOKEN_FROM_SERVER_TAB"
      }
    }
  }
}

Add to `~/.claude.json` or your project's `.mcp.json`.

> ⚠️ **The token is required, and the endpoint is the root path `/` — not `/sse`.** > Copy the token from the **Server** tab of the BurpMCP-Ultra panel in Burp. Without it the > server returns `401`, and clients like Claude Code then fall back to OAuth discovery and > fail with `SDK auth failed: HTTP 404: Invalid OAuth error response`.

> 💡 **MCP client can't set headers?** Use the token-in-path URL — no `headers` block needed > (GitHub issue #11). Copy it with **"Copy No-Headers Config"** on the Server tab: > > ```json > { "mcpServers": { "burp": { "type": "sse", "url": "http://127.0.0.1:9876/PASTE_TOKEN_FROM_SERVER_TAB/" } } } > ``` > > **Keep the trailing slash** — it is what makes the token survive onto the SSE back-channel. > A `?token=…` query does **not** work for MCP: the SDK advertises its POST endpoint as the > relative reference `?sessionId=…`, which per RFC 3986 §5.3 replaces the query (so the token is > dropped and every message `401`s) while preserving the path. Note the token becomes part of the > URL, so prefer the header form when your client supports it.

4. Open Dashboard

Browse to **http://127.0.0.1:9878** for the real-time web dashboard.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 629 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # BurpMCP-Ultra
  3. **The most powerful MCP server for Burp Suite Professional.**
  4. Drop a single JAR into Burp, connect Claude Code (or any MCP client), and drive every
  5. part of Burp Suite programmatically through AI agents.
  6. [![Latest release](https://img.shields.io/github/v/release/Cy-S3c/BurpMCP-Ultra?color=1f6feb&label=release)](https://github.com/Cy-S3c/BurpMCP-Ultra/releases/latest)
  7. [![Build](https://github.com/Cy-S3c/BurpMCP-Ultra/actions/workflows/build.yml/badge.svg)](https://github.com/Cy-S3c/BurpMCP-Ultra/actions/workflows/build.yml)
  8. [![License](https://img.shields.io/badge/license-MIT-3fb950)](#license)
  9. [![Burp Suite](https://img.shields.io/badge/Burp%20Suite-Professional-ff6633)](https://portswigger.net/burp)
  10. [![Kotlin](https://img.shields.io/badge/Kotlin-2.1.20-7F52FF?logo=kotlin&logoColor=white)](https://kotlinlang.org)
  11. [![MCP tools](https://img.shields.io/badge/MCP%20tools-150-8957e5)](#tools)
  12. [![Stars](https://img.shields.io/github/stars/Cy-S3c/BurpMCP-Ultra?style=flat&color=e3b341)](https://github.com/Cy-S3c/BurpMCP-Ultra/stargazers)
  13. [![Telegram](https://img.shields.io/badge/Telegram-%40D4RK__V0RT3X-2CA5E0?logo=telegram&logoColor=white)](https://t.me/D4RK_V0RT3X)
  14. **150 Tools** &bull; **8 Resources** &bull; **17 Event Types** &bull; Real-time Dashboard &bull; Hardened Localhost Security
  15. [Quick Start](#quick-start) &bull;
  16. [Tools](#tools) &bull;
  17. [Features](#highlight-features) &bull;
  18. [Security](#security-model) &bull;
  19. [Dashboard](#web-dashboard) &bull;
  20. [Setup Guides](#setup-guides) &bull;
  21. [Contact](#contact--support)
  22. </div>
  23. ---
  24. BurpMCP-Ultra is a native **Kotlin** Burp Suite extension with an embedded **MCP (Model
  25. Context Protocol)** server. It exposes Burp's Montoya API as 150 structured tools over a
  26. token-secured local SSE transport, so an AI agent can run proxy history analysis, active
  27. scans, fuzzing, race conditions, OOB testing, custom scan checks, and guided exploitation
  28. — all from natural language.
  29. ## Why BurpMCP-Ultra?
  30. | | BurpMCP-Ultra | burp-ai-agent | PortSwigger Official |
  31. |---|:---:|:---:|:---:|
  32. | **MCP Tools** | **150** | 53 | 12 |
  33. | **Custom Scan Checks** | BCheck + Script | – | – |
  34. | **Guided Injection Probe** | SQLi / SSTI / LFI oracles | – | – |
  35. | **JWT Attacks** | alg:none, RS→HS, crack | – | – |
  36. | **Access-Control Sweep** | IDOR / privesc across identities | – | – |
  37. | **WebSocket Testing** | Full lifecycle | – | – |
  38. | **Inline Fuzzer** | 3 modes (FUZZ / Marker / Offset) | – | – |
  39. | **Race Condition Testing** | Single-packet attack | – | – |
  40. | **API Schema Import** | OpenAPI / Swagger + `$ref` | – | – |
  41. | **Passive Intel Extraction** | 30+ patterns, entropy de-noised | – | – |
  42. | **Recon** | JS endpoints, content/param discovery | – | – |
  43. | **Real-time Dashboard** | Web + Swing | – | – |
  44. | **Hardened Localhost Security** | Host + Origin + token, scope gate | – | – |
  45. | **Collaborator OOB** | Full create / poll / correlate | Partial | Partial |
  46. > Competitor counts are indicative, based on each project's public tool list.
  47. ---
  48. ## Quick Start
  49. ### 1. Build
  50. ```bash
  51. git clone https://github.com/Cy-S3c/BurpMCP-Ultra.git
  52. cd BurpMCP-Ultra
  53. ./gradlew shadowJar
  54. ```
  55. Output: `build/libs/burpmcp-ultra-2.3.1.jar` (~13 MB). A **JDK 17–21** must be installed —
  56. see [Building from Source](#building-from-source). Pre-built JARs are on the
  57. [Releases](https://github.com/Cy-S3c/BurpMCP-Ultra/releases) page.
  58. ### 2. Load into Burp
  59. 1. Burp Suite Pro → **Extensions** → **Add**
  60. 2. Select the JAR
  61. 3. The **BurpMCP-Ultra** tab appears with a green "Running" status and your connection token
  62. ### 3. Connect Claude Code
  63. ```json
  64. {
  65. "mcpServers": {
  66. "burp": {
  67. "type": "sse",
  68. "url": "http://127.0.0.1:9876/",
  69. "headers": {
  70. "Authorization": "Bearer PASTE_TOKEN_FROM_SERVER_TAB"
  71. }
  72. }
  73. }
  74. }
  75. ```
  76. Add to `~/.claude.json` or your project's `.mcp.json`.
  77. > ⚠️ **The token is required, and the endpoint is the root path `/` — not `/sse`.**
  78. > Copy the token from the **Server** tab of the BurpMCP-Ultra panel in Burp. Without it the
  79. > server returns `401`, and clients like Claude Code then fall back to OAuth discovery and
  80. > fail with `SDK auth failed: HTTP 404: Invalid OAuth error response`.
  81. > 💡 **MCP client can't set headers?** Use the token-in-path URL — no `headers` block needed
  82. > (GitHub issue #11). Copy it with **"Copy No-Headers Config"** on the Server tab:
  83. >
  84. > ```json
  85. > { "mcpServers": { "burp": { "type": "sse", "url": "http://127.0.0.1:9876/PASTE_TOKEN_FROM_SERVER_TAB/" } } }
  86. > ```
  87. >
  88. > **Keep the trailing slash** — it is what makes the token survive onto the SSE back-channel.
  89. > A `?token=…` query does **not** work for MCP: the SDK advertises its POST endpoint as the
  90. > relative reference `?sessionId=…`, which per RFC 3986 §5.3 replaces the query (so the token is
  91. > dropped and every message `401`s) while preserving the path. Note the token becomes part of the
  92. > URL, so prefer the header form when your client supports it.
  93. ### 4. Open Dashboard
  94. Browse to **http://127.0.0.1:9878** for the real-time web dashboard.
  95. ---
  96. ## Tools
  97. **150 MCP tools** across 37 categories. Names are stable; the authoritative count is
  98. `server.tools.size`, surfaced in the Server tab.
  99. ### Proxy (13)
  100. | Tool | Description |
  101. |------|-------------|
  102. | `proxy_history` | Get HTTP proxy history with filtering (host, method, status, MIME, scope) |
  103. | `proxy_history_search` | Regex search across proxy history (URL, headers, body) |
  104. | `proxy_websocket_history` | Get WebSocket proxy history |
  105. | `proxy_websocket_history_search` | Regex search WebSocket history |
  106. | `proxy_intercept_enable` / `proxy_intercept_disable` / `proxy_intercept_status` | Control & inspect interception |
  107. | `proxy_annotate` | Add highlight color and comment to a history item |
  108. | `proxy_set_request_rule` / `proxy_set_response_rule` | Auto modify/drop/tag matching proxy traffic |
  109. | `proxy_list_rules` / `proxy_remove_rule` | Manage proxy rules |
  110. | `proxy_auto_auth` | One-command auth-header injection for all matching requests |
  111. ### HTTP (13)
  112. | Tool | Description |
  113. |------|-------------|
  114. | `http_send_request` | Send HTTP request (structured or raw, HTTP/1.1 or HTTP/2) |
  115. | `http_send_requests_parallel` | Send multiple requests in parallel (batch ops, races) |
  116. | `http_send_request_chain` | Multi-step request sequence with token extraction between steps |
  117. | `http_send_raw_bytes` | Byte-level request for smuggling and CRLF injection |
  118. | `http_fuzz` | Inline fuzzer — FUZZ keyword, `§marker§`, or byte-offset modes + payload libraries |
  119. | `http_race` | Race-condition testing — fire N requests simultaneously |
  120. | `http_cookie_jar_get` / `http_cookie_jar_set` | Read/write Burp's cookie jar |
  121. | `http_analyze_keywords` | Analyze a response for keyword occurrences |
  122. | `http_analyze_variations` | Detect response variations (blind injection) |
  123. | `http_set_traffic_rule` / `http_list_traffic_rules` / `http_remove_traffic_rule` | Global request/response rules |
  124. ### Scanner (13)
  125. | Tool | Description |
  126. |------|-------------|
  127. | `scanner_start_crawl` | Start a web crawl from seed URLs |
  128. | `scanner_start_audit` | Start active/passive scan with optional auth config |
  129. | `scanner_task_status` / `scanner_task_list` / `scanner_task_delete` | Manage scan/crawl tasks |
  130. | `scanner_task_add_request` | Add a request to a running audit |
  131. | `scanner_task_issues` | Get issues from a specific task |
  132. | `scanner_get_all_issues` | All issues with severity/confidence filter |
  133. | `scanner_generate_report` | Generate HTML/XML scan report |
  134. | `scanner_create_issue` | Create a custom audit issue |
  135. | `scanner_import_bcheck` | Import a BCheck script for custom scanning |
  136. | `scanner_register_check` / `scanner_unregister_check` | Register / deregister a custom scan check |
  137. ### Collaborator (7)
  138. | Tool | Description |
  139. |------|-------------|
  140. | `collaborator_create_client` | Create a Collaborator client for OOB testing |
  141. | `collaborator_restore_client` | Restore a client from its secret key |
  142. | `collaborator_generate_payload` | Generate a Collaborator payload |
  143. | `collaborator_default_payload` | Generate a payload on a shared default client (quick OOB) |
  144. | `collaborator_poll` | Poll for DNS / HTTP / SMTP interactions (decodes DNS qnames) |
  145. | `collaborator_server_info` | Get the Collaborator server address |
  146. | `collaborator_get_secret` | Get the client secret key for session persistence |
  147. ### Intruder & Repeater (4)
  148. | Tool | Description |
  149. |------|-------------|
  150. | `intruder_send` / `intruder_send_with_positions` | Send to Intruder (auto or explicit positions) |
  151. | `intruder_register_payload_processor` | Register a custom payload processor |
  152. | `repeater_send` | Send a request to a Repeater tab |
  153. ### WebSocket (7)
  154. | Tool | Description |
  155. |------|-------------|
  156. | `websocket_create` | Create a WebSocket connection |
  157. | `websocket_send_text` / `websocket_send_binary` | Send text / binary messages |
  158. | `websocket_close` / `websocket_list` | Close / list connections |
  159. | `websocket_get_messages` | Get messages with a direction filter |
  160. | `websocket_set_intercept_rule` | Auto-intercept WebSocket messages |
  161. ### Offensive & Recon (11)
  162. | Tool | Description |
  163. |------|-------------|
  164. | `injection_probe` | Guided **SQLi / SSTI / LFI** with confirmation oracles (SQL-error fingerprints, time-delay, template math-eval, file markers) — not blind fuzzing |
  165. | `jwt_attack` | JWT offense — `alg:none`, **RS→HS** key confusion, weak-secret cracking, structural analysis |
  166. | `access_control_sweep` | Batch **broken-access-control / IDOR** across multiple identities |
  167. | `graphql_probe` | GraphQL **introspection** + field-suggestion enumeration |
  168. | `cors_probe` | Detect **CORS** misconfigurations (reflected / null origin, credentialed) |
  169. | `recon_fingerprint` | Technology + WAF fingerprinting |
  170. | `recon_js_endpoints` | Harvest endpoints/URLs from JavaScript files |
  171. | `recon_content_discovery` | Path / content discovery against a target |
  172. | `recon_param_mine` | Mine hidden & reflected parameters |
  173. | `findings_add` / `findings_list` | The agent's deduplicated working store of findings |
  174. > Offensive tools that issue live requests are **scope-gated** (see [Security](#security-model)).
  175. ### Analysis (7)
  176. | Tool | Description |
  177. |------|-------------|
  178. | `analyze_request` / `analyze_response` | Parse HTTP messages into structured components |
  179. | `analyze_find_reflected` | Find parameter values reflected in a response (XSS surface) |
  180. | `analyze_extract_params` | Extract all parameters (URL, body, cookie, header, JSON) |
  181. | `analyze_insertion_points` | Scanner-style insertion points (incl. JSON-body leaves) |
  182. | `analyze_diff` | Compare two requests or responses |
  183. | `analyze_response_body_search` | Search all proxy response bodies for a pattern |
  184. ### Advanced Analysis (3)
  185. | Tool | Description |
  186. |------|-------------|
  187. | `auth_diff` | Compare responses across auth levels → IDOR / privesc verdict |
  188. | `api_import_openapi` | Import OpenAPI/Swagger (with `$ref` resolution), generate requests, populate sitemap |
  189. | `passive_intel` | Extract secrets/tokens/IPs from proxy history — 30+ patterns, entropy de-noised |
  190. ### Utilities (12)
  191. | Tool | Description |
  192. |------|-------------|
  193. | `util_url_encode` / `util_url_decode` | URL encoding / decoding |
  194. | `util_base64_encode` / `util_base64_decode` | Base64 encoding / decoding |
  195. | `util_html_encode` | HTML entity encoding |
  196. | `util_hash` | Hashing (MD5, SHA1, SHA256, SHA384, SHA512) |
  197. | `util_compress` / `util_decompress` | Gzip / deflate / brotli |
  198. | `util_random_string` / `util_random_bytes` | Random generators |
  199. | `util_jwt_decode` | Decode a JWT (header, payload, expiry) |
  200. | `util_decode_smart` | Auto-detect and decode multi-layer encoding |
  201. ### Custom Scan Checks — BCheck (5) + Script (5)
  202. | Tool | Description |
  203. |------|-------------|
  204. | `bcheck_create` | Generate & deploy a BCheck from structured parameters |
  205. | `bcheck_import` | Import a raw BCheck DSL script |
  206. | `bcheck_templates` / `bcheck_list` / `bcheck_remove` | Templates, list, remove BChecks |
  207. | `scancheck_create_passive` | Passive check with multi-condition matching |
  208. | `scancheck_create_active` | Multi-step active check with payload chains |
  209. | `scancheck_templates` / `scancheck_list` / `scancheck_remove` | Templates, list, deregister script checks |
  210. ### Scope & Sitemap (8)
  211. | Tool | Description |
  212. |------|-------------|
  213. | `scope_check` / `scope_include` / `scope_exclude` / `scope_get_config` | Target scope management |
  214. | `sitemap_query` / `sitemap_get_issues` / `sitemap_add_request` / `sitemap_add_issue` | Sitemap operations |
  215. ### Config & Burp (16)
  216. | Tool | Description |
  217. |------|-------------|
  218. | `burp_version` | Burp version and edition |
  219. | `burp_export_project_config` / `burp_import_project_config` | Project config as JSON |
  220. | `burp_export_user_config` / `burp_import_user_config` | User config as JSON |
  221. | `burp_task_engine_state` / `burp_task_engine_set` | Pause/resume all background tasks |
  222. | `burp_command_line_args` | Startup arguments |
  223. | `burp_shutdown` | Shut down Burp (gated — see [Security](#security-model)) |
  224. | `config_proxy_listeners_list` / `config_proxy_listener_add` / `config_proxy_listener_remove` | Manage proxy listeners |
  225. | `config_match_replace_add` / `config_match_replace_list` / `config_match_replace_remove` | Manage match-and-replace rules |
  226. | `config_upstream_proxy_set` | Configure an upstream proxy (Tor, corporate) |
  227. ### Platform (25)
  228. | Tool | Description |
  229. |------|-------------|
  230. | `session_create_token_rule` / `session_list_rules` / `session_remove_rule` | Session-handling rules (extract → inject) |
  231. | `events_get` / `events_get_by_type` / `events_subscribe` / `events_unsubscribe` / `events_clear` | Event system |
  232. | `persistence_store` / `persistence_get` / `persistence_delete` / `persistence_list` | Project data storage |
  233. | `preference_store` / `preference_get` | Global preferences |
  234. | `decoder_send` / `comparer_send` | Send to Decoder / Comparer |
  235. | `organizer_send` / `organizer_get_items` | Organizer management |
  236. | `log_message` / `log_event` | Burp logging |
  237. | `ai_status` / `ai_prompt` | Burp AI integration (Burp 2025+) |
  238. | `bambda_import` | Import Bambda scripts |
  239. | `project_info` / `extension_info` | Project & extension metadata |
  240. ### Resources (8)
  241. Read-only MCP resources an agent can fetch without a tool call:
  242. `burp://proxy/history` · `burp://proxy/websocket/history` · `burp://scanner/issues` ·
  243. `burp://sitemap` · `burp://scope` · `burp://config/project` · `burp://config/user` ·
  244. `burp://organizer/items`
  245. ---
  246. ## Highlight Features
  247. ### Guided Injection Probe
  248. ```
  249. injection_probe(
  250. request: "GET /item?id=FUZZ HTTP/1.1\r\nHost: shop.com\r\n\r\n",
  251. host: "shop.com", port: 443,
  252. classes: ["sqli", "ssti", "lfi"] # optional; default all
  253. )
  254. ```
  255. Marks the injection point with `FUZZ`, then **confirms** vulnerabilities with deterministic
  256. oracles — SQL error fingerprints, time-delay analysis, template math-evaluation
  257. (`1337*1337 → 1787569`), and file-content markers — returning only confirmed findings with
  258. the triggering payload. For blind/OOB classes, pair `collaborator_*` with `http_fuzz`.
  259. ### JWT Attacks
  260. ```
  261. jwt_attack(token: "eyJ...", mode: "crack", wordlist: ["secret", "changeme", ...])
  262. ```
  263. `alg:none` forgery, **RS→HS** algorithm-confusion forging, weak-secret dictionary cracking,
  264. and full structural analysis.
  265. ### Access-Control Sweep
  266. ```
  267. auth_diff / access_control_sweep
  268. request: "GET /api/users/1 HTTP/1.1\r\nHost: api.com\r\n\r\n",
  269. auth_levels: [
  270. {"name": "admin", "header_name": "Authorization", "header_value": "Bearer admin"},
  271. {"name": "user", "header_name": "Authorization", "header_value": "Bearer user"},
  272. {"name": "none"}
  273. ]
  274. ```
  275. Replays the same request(s) across identities, diffs the responses, and flags **IDOR**,
  276. privilege escalation, and missing authorization.
  277. ### Race Condition Testing
  278. ```
  279. http_race(request: "POST /api/transfer HTTP/1.1\r\nHost: bank.com\r\n\r\n{\"amount\":100}",
  280. host: "bank.com", port: 443, count: 20)
  281. ```
  282. Fires 20 identical requests simultaneously via Burp's parallel engine and analyzes
  283. status/length distributions to detect TOCTOU, double-spend, and limit-bypass bugs.
  284. ### Inline Fuzzer (3 modes)
  285. ```
  286. # FUZZ keyword
  287. http_fuzz(request: "GET /api?id=FUZZ HTTP/1.1\r\nHost: api.com\r\n\r\n", host: "api.com",
  288. port: 443, payloads: ["1", "admin", "../../etc/passwd"])
  289. # §section§ markers (like Intruder) | # byte offsets: positions: [[12, 15]]
  290. # built-in payload libraries via: payload_library: "xss" | "sqli" | "lfi" | ...
  291. ```
  292. ### Custom Scan Checks
  293. ```
  294. # BCheck DSL
  295. bcheck_create(name: "AWS Key Leak", type: "passive_response",
  296. match_pattern: "AKIA[0-9A-Z]{16}", severity: "high", confidence: "firm")
  297. # Script mode — multi-step active check
  298. scancheck_create_active(name: "SSTI", steps: [
  299. {"payload": "{{7*7}}", "response_conditions": [
  300. {"location": "response_body", "pattern": "49", "condition_type": "contains"}]}])
  301. ```
  302. ### API Schema Import
  303. ```
  304. api_import_openapi(spec_json: "<swagger/openapi JSON>", auth_header: "Authorization",
  305. auth_value: "Bearer …", send_requests: true, add_to_sitemap: true)
  306. ```
  307. Parses OpenAPI 3.x / Swagger 2.0 (resolving `$ref`), generates real requests with sample
  308. parameters/bodies for every endpoint, and optionally sends them — populating proxy history
  309. and sitemap. Out-of-scope sends are skipped and reported.
  310. ### Passive Intelligence Extraction
  311. ```
  312. passive_intel(max_items: 2000, in_scope_only: true)
  313. ```
  314. Scans captured traffic for 30+ patterns with entropy de-noising to cut false positives:
  315. - **Cloud credentials** — AWS keys, Google/Slack/Stripe/GitHub tokens
  316. - **Tokens & secrets** — JWTs, Bearer/Basic auth, private keys
  317. - **Personal data** — emails, internal IPs, phone numbers
  318. - **Cloud resources** — S3/Azure/GCS buckets
  319. - **Infrastructure** — internal URLs, GraphQL endpoints, API paths
  320. - **Errors & fingerprints** — stack traces, SQL errors, server/framework versions
  321. - **Sensitive paths** — `/admin`, `/.env`, `/.git`, `/debug`, `/actuator`
  322. ---
  323. ## Security Model
  324. BurpMCP-Ultra runs three local servers (SSE `9876`/`9877`, dashboard `9878`). Binding to
  325. `127.0.0.1` is **not** a trust boundary, so the transport is hardened and offensive tools are
  326. governed by **operator-only** controls the agent cannot change.
  327. > **Port already in use?** PortSwigger's own **MCP Server** extension also defaults to **9876**, so
  328. > running both at once clashes. Move this extension with the `mcp_sse_port` / `mcp_http_port` /
  329. > `mcp_dashboard_port` preferences (or `-Dburpmcp.ssePort=…`), then reload. On a clash the
  330. > extension now says so explicitly in the Errors tab — it is *not* the JDK-version problem.
  331. **Transport hardening**
  332. - **Host-header allowlist** — defeats DNS rebinding.
  333. - **Origin lockdown** — rejects cross-origin browser requests; CORS only advertises loopback.
  334. - **Per-session token** — required on every request (`Authorization: Bearer`, `mcp_token`
  335. cookie, `?token=`, or the first URL **path** segment `/<token>/` for header-less MCP clients).
  336. The dashboard uses an `HttpOnly` cookie, so the token never lives in a URL there. A back-channel
  337. `POST ?sessionId=…` may instead present a live session id — a 122-bit capability the server
  338. discloses only over an already-authenticated stream, never a bypass.
  339. **Operator governance** (configured in Burp, not via MCP)
  340. - `mcp_scope_mode` — `off` / `warn` / `enforce`. Every live-request tool passes through a
  341. central **scope gate** (`http_*`, `auth_diff`, `api_import_openapi`, `recon_*`, `graphql_probe`,
  342. `cors_probe`, `access_control_sweep`, `injection_probe`).
  343. - `mcp_allow_destructive` — default **false**; blocks `burp_shutdown` and config import.
  344. - **Append-only audit log** of security-relevant tool calls (`~/.burpmcp-ultra-audit.jsonl`).
  345. Additional defenses: ReDoS-safe regex, CRLF header validation, and response/WebSocket size caps.
  346. ---
  347. ## Web Dashboard
  348. Open **http://127.0.0.1:9878** for the real-time dashboard:
  349. - **Live Activity Stream** with noise filtering (auto-hides Google/Apple/Microsoft connectivity checks)
  350. - **Attack Vector Detection** — badges for AUTH, API, PARAMS, UPLOAD, ADMIN, DATA endpoints
  351. - **Request Detail Panel** — click any item for full request info + send-to-tool actions
  352. - **Stats Bar** — live counters for events, in-scope hosts, and attack-vector categories
  353. - **Filter Controls** — type filters, URL search, noise toggle
  354. - **Active Rules** — view all proxy, traffic, and session rules
  355. - **Connection Info** — transport URLs and a ready-to-paste MCP client config
  356. ---
  357. ## Setup Guides
  358. <details>
  359. <summary><strong>Claude Code (Direct SSE)</strong></summary>
  360. ```json
  361. {
  362. "mcpServers": {
  363. "burp": {
  364. "type": "sse",
  365. "url": "http://127.0.0.1:9876/",
  366. "headers": { "Authorization": "Bearer PASTE_TOKEN_FROM_SERVER_TAB" }
  367. }
  368. }
  369. }
  370. ```
  371. The token comes from the **Server** tab. The endpoint is the root path `/` (not `/sse`). If your
  372. client cannot set headers, drop the `headers` block and put the token in the path instead —
  373. `"url": "http://127.0.0.1:9876/<token>/"` (keep the trailing slash). Config locations:
  374. `~/.claude.json` (global) or `.mcp.json` (per-project).
  375. </details>
  376. <details>
  377. <summary><strong>Claude Code via Caddy (recommended for stability)</strong></summary>
  378. Caddy prevents SSE timeout disconnections and provides reliable buffering.
  379. ```bash
  380. sudo apt install caddy
  381. ```
  382. `/etc/caddy/Caddyfile`:
  383. ```
  384. :9900 {
  385. reverse_proxy 127.0.0.1:9876 {
  386. transport http { read_timeout 0 write_timeout 0 response_header_timeout 0 }
  387. flush_interval -1
  388. header_up Connection {>Connection}
  389. header_up Upgrade {>Upgrade}
  390. }
  391. }
  392. ```
  393. ```bash
  394. sudo systemctl restart caddy
  395. ```
  396. Then point your config at port 9900:
  397. ```json
  398. {
  399. "mcpServers": {
  400. "burp": {
  401. "type": "sse",
  402. "url": "http://127.0.0.1:9900/",
  403. "headers": { "Authorization": "Bearer PASTE_TOKEN_FROM_SERVER_TAB" }
  404. }
  405. }
  406. }
  407. ```
  408. Pre-built Caddyfile: [`configs/Caddyfile`](configs/Caddyfile)
  409. </details>
  410. <details>
  411. <summary><strong>Claude Desktop (stdio via proxy)</strong></summary>
  412. Claude Desktop only supports stdio transport. Bridge it with supergateway:
  413. ```json
  414. {
  415. "mcpServers": {
  416. "burp": {
  417. "command": "npx",
  418. "args": ["-y", "supergateway", "--sse", "http://127.0.0.1:9876/", "--header", "Authorization: Bearer PASTE_TOKEN_FROM_SERVER_TAB"]
  419. }
  420. }
  421. }
  422. ```
  423. </details>
  424. <details>
  425. <summary><strong>Automated setup script</strong></summary>
  426. ```bash
  427. chmod +x configs/setup.sh
  428. ./configs/setup.sh
  429. ```
  430. Builds the JAR, optionally configures Caddy, and prints the MCP config to add.
  431. </details>
  432. ---
  433. ## Architecture
  434. ```
  435. +---------------------------------------------------+
  436. | BURP SUITE PRO |
  437. | +---------------------------------------------+ |
  438. | | BurpMCP-Ultra Extension | |
  439. | | | |
  440. | | Montoya API --> Bridge Layer (32 bridges) | |
  441. | | | | | |
  442. | | Event Bus Tool Registry (150 tools) | |
  443. | | | | | |
  444. | | +------- MCP Server Core -------+ | |
  445. | | (Kotlin SDK 0.8.3) | | |
  446. | | | | | |
  447. | | +----------+----------+ | | |
  448. | | SSE :9876 SSE :9877 Dashboard | | |
  449. | | :9878 | | |
  450. | +---------------------------------------------+ |
  451. +---------------------------------------------------+
  452. ```
  453. ## Tech Stack
  454. | Component | Version |
  455. |-----------|---------|
  456. | Kotlin | 2.1.20 |
  457. | JVM Target | 17 |
  458. | Montoya API | 2026.2 |
  459. | MCP Kotlin SDK | 0.8.3 |
  460. | Ktor CIO | 3.2.3 |
  461. | kotlinx.serialization | 1.8.1 |
  462. | Shadow JAR | 8.1.1 |
  463. ## Requirements
  464. **To run (inside Burp):**
  465. - Burp Suite Professional 2025.x or later
  466. - Java 17+ — provided by Burp's bundled JRE (nothing to install)
  467. **To build from source:**
  468. - A **JDK 17–21** (LTS) installed. Building under Java 22+ (including Burp's bundled Java 25)
  469. is incompatible with the Kotlin 2.1.20 / Ktor 3.2.3 / MCP SDK toolchain and yields a JAR
  470. whose MCP SSE ports silently fail to bind. You do **not** need JDK 17 as your default,
  471. though: the build pins both compilation and the Gradle daemon to a JDK 17 toolchain
  472. (`gradle/gradle-daemon-jvm.properties`), so `./gradlew` auto-runs under JDK 17 as long as
  473. one is installed and discoverable.
  474. - Gradle 8.x — included via the committed wrapper (`./gradlew` / `gradlew.bat`).
  475. ## Building from Source
  476. The Gradle wrapper is committed, so no separate Gradle install is needed.
  477. **Linux / macOS**
  478. ```bash
  479. git clone https://github.com/Cy-S3c/BurpMCP-Ultra.git
  480. cd BurpMCP-Ultra
  481. # Gradle auto-selects an installed JDK 17 for the build daemon, so this works even if your
  482. # default `java` is Burp's Java 25. If no JDK 17 is discoverable, install one (or set JAVA_HOME).
  483. ./gradlew shadowJar
  484. # Output: build/libs/burpmcp-ultra-2.3.1.jar
  485. ```
  486. **Windows (PowerShell / cmd)**
  487. ```bat
  488. git clone https://github.com/Cy-S3c/BurpMCP-Ultra.git
  489. cd BurpMCP-Ultra
  490. :: Gradle auto-selects an installed JDK 17 for the build daemon, so this works even if your
  491. :: default java is Burp's Java 25. If no JDK 17 is discoverable, install one (or set JAVA_HOME).
  492. gradlew.bat shadowJar
  493. :: Output: build\libs\burpmcp-ultra-2.3.1.jar
  494. ```
  495. > If no JDK 17 is found, Gradle fails with a clear "no compatible daemon JVM" error instead of
  496. > silently producing a broken JAR. Kotlin 2.1.20 cannot even *compile* the Gradle build scripts
  497. > under Java 22+, which is why the daemon is pinned to JDK 17.
  498. ## Project Structure
  499. ```
  500. BurpMCP-Ultra/
  501. ├── build.gradle.kts # Build configuration
  502. ├── gradle/ # Wrapper + daemon-JVM pin (JDK 17)
  503. ├── configs/ # Ready-to-use config files (Caddyfile, MCP JSON, setup.sh)
  504. ├── src/main/kotlin/com/burpmcp/ultra/
  505. │ ├── core/ # Extension entry point + helpers
  506. │ ├── bridge/ # 32 Montoya API bridges
  507. │ ├── tools/ # 37 tool category modules (150 tools)
  508. │ ├── safety/ # Scope gate, action policy, ReDoS-safe regex
  509. │ ├── transport/ # MCP server + dashboard + security
  510. │ ├── events/ # Unified event bus
  511. │ ├── state/ # State management
  512. │ └── ui/ # Swing UI tab
  513. ├── src/test/ # 105 unit tests
  514. └── docs/ # Tool catalog + capability review
  515. ```
  516. ---
  517. ## Contact & Support
  518. - 🐛 **Bugs & feature requests:** [GitHub Issues](https://github.com/Cy-S3c/BurpMCP-Ultra/issues)
  519. - 📦 **Releases & changelog:** [GitHub Releases](https://github.com/Cy-S3c/BurpMCP-Ultra/releases)
  520. - 💬 **Quick reach:** Telegram [**@D4RK_V0RT3X**](https://t.me/D4RK_V0RT3X)
  521. ## License
  522. [MIT](LICENSE)
  523. ---
  524. <div align="center">
  525. Built for bug-bounty hunters and pentesters who want AI-powered Burp Suite automation.
  526. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.