Burp MCP Server

A Burp Suite extension that exposes your running Burp as MCP tools. An AI agent can send HTTP requests, read proxy history and the site map, drive the scanner, and hand requests to Repeater, Intruder, Comparer, or Organizer.

It runs in Burp's JVM and speaks JSON-RPC 2.0 over HTTP, on TCP or a per-project Unix socket.

Getting the extension

Download burp-mcp-server.jar from the latest release, or build current main:

git clone https://github.com/N0K0/burp-mcp.git
cd burp-mcp
mvn clean package -DskipTests

JDK 17 or newer and Maven 3.9 or newer are required. The build writes target/burp-mcp-server.jar.

Load it under Extensions -> Installed -> Add -> Java. Burp does not reload Java extensions, so remove and re-add the entry after a rebuild. On WSL with /mnt/c present, the build also copies the jar to C:\Users\nikolas\Downloads\.

Checking it works

# list the tools
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"1"}' \
  http://127.0.0.1:4444/

# ask Burp about itself
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"burp_info","arguments":{}},"id":"2"}' \
  http://127.0.0.1:4444/

# health check
curl -s http://127.0.0.1:4444/health

The same calls work over the Unix socket. Get the path from burp_info -> mcpSocketPath, or from the Status tab:

SOCK=$(curl -s -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"burp_info","arguments":{}},"id":"1"}' \
  http://127.0.0.1:4444/ \
  | python3 -c "import json,sys; print(json.loads(json.load(sys.stdin)['result']['content'][0]['text'])['mcpSocketPath'])")

curl -s --unix-socket "$SOCK" http://localhost/health

The Tool Tester shows the same output; burp_info also reports the active access-control state (scope enforcement, approval timing, pending requests, and session grants) so an agent can see why a call was blocked:

How it fits together

The extension runs inside Burp's JVM on the Montoya API, so an agent works on the project you have open: the same proxy history, site map, scope, cookies, and Professional license.

It adds a "Burp MCP" tab with six screens: Status (Start/Stop/Restart, metrics, request log), Settings, Tool Tester, Permissions, Approvals, and Messages.

Compared with PortSwigger's MCP server

PortSwigger ships an official MCP server (Kotlin, GPL-3.0). Both let MCP clients drive Burp; they make different tradeoffs. Official details below are from its repository as of October 2026.

The tool sets overlap but are not identical. The official server has get_active_editor_contents / set_active_editor_contents (the focused message editor, for tight human-in-the-loop work), generate_random_string, and HTTP/2 Repeater tabs. This one adds the scanner workflow (scanner_start_audit, scanner_start_crawl, crawl status/stop, scanner_bcheck_import, scanner_generate_report), scope control, sitemap_search, the cookie jar, http_diff_responses, http_keyword_search, and the Organizer/Comparer/Decoder handoffs.

Use the official server when you want the supported default, per-call approval dialogs, or an SSE/stdio-only client. Use this one when you want the larger tool set, several Burp projects at once, pre-authorized read-only or custom access for unattended runs, or auth, metrics, and logs.

Transports and multiple projects

TCP listens on mcp_port, 4444 by default.

The Unix socket is on by default next to the open project file, so ~/burp-projects/exness.burp gets ~/burp-projects/exness.sock. Each project gets its own socket, and several Burp instances can run at once. Temporary projects, unlocatable project files, and over-long paths fall back to <tmp>/burp-mcp-<hash>.sock. Set socket_path or BURP_MCP_SOCKET_PATH to override; set socket_enabled=false to disable.

If another process holds 4444, this instance keeps serving on its socket and the Status tab reports the conflict. Close the other instance and press Restart.

Both transports use the same HTTP JSON-RPC, including auth, permissions, rate limits, and /health. The socket handles one request per connection (Connection: close), is owner-only, and is removed on Stop, Restart, or unload; a crash leaves a stale file that the next start replaces. Python clients need an AF_UNIX connector; curl --unix-socket works as is.

The tools

53 tools. Aliases work too: proxy_list maps to proxy_history_list, send_request to http_send_request. Permissions and metrics use canonical names, so disabling a tool also disables its aliases.

Send and shape HTTP

Read what Burp has seen

Hand work to Burp's own tools

Scanner and crawler (Professional)

Out-of-band testing (Professional)

Scope, project, and settings

Encode, compare, search

Server health

burp_metrics returns uptime, request counts, latency percentiles, per-tool counts, cache hit rate, and active connections. The same numbers are at GET /health?format=prometheus.

A worked example

Prompt: "Map everything under https://shop.example.test and look at the checkout flow." The agent alternates between reading Burp's state and sending requests:

1. scope_check on the seed.
2. sitemap_list, sitemap_search, and proxy_history_list for what Burp already captured.
3. http_send_request to cover gaps and exercise checkout.
4. http_send_to_repeater or http_send_to_organizer for manual follow-up.
5. On Professional: scanner_start_audit, then scanner_issues_list_filtered at severity HIGH, scanner_get_issue, and scanner_generate_report.
6. For blind bugs: collaborator_generate_payload, use the payload, then collaborator_interactions.

The extension runs nothing on its own; every call goes through the permission rules below.

Connecting a client

Any MCP client that supports remote HTTP servers works.

Hermes:

# ~/.hermes/config.yaml
mcp_servers:
  burp:
    url: http://127.0.0.1:4444

Claude Desktop:

{
  "mcpServers": {
    "burp": {
      "url": "http://127.0.0.1:4444"
    }
  }
}

opencode:

{
  "mcp": {
    "servers": {
      "burp": {
        "type": "remote",
        "url": "http://127.0.0.1:4444/"
      }
    }
  }
}

Custom clients POST JSON-RPC to / with initialize, tools/list, and tools/call. GET /health returns {"status":"ok"} or {"status":"error"}.

Permissions and safety

Four modes in the Permissions tab:

• Read-Write (default): everything allowed.
• Read-Only: queries only. That covers burp_info, project_create, burp_metrics, sitemap_*, proxy_history_*, proxy_intercept_status, proxy_websocket_history_list, websocket_history_get, scope_check, scope_list, organizer_list, task_engine_status, scanner_crawl_status, cookie_list, decoder_*, http_parse_*, http_get_request, http_diff_responses, http_keyword_search, config_get, config_list_preferences, the scanner issue reads, and collaborator_interactions.
• Prompt: reads run, writes ask the operator first.
• Custom: per-tool policy — click a tool to cycle Allow → Prompt → Deny. Unlisted tools stay allowed.

The sensitivity switch blocks scope_set, config_set, scanner_start_audit, scanner_start_crawl, scanner_crawl_stop, scanner_bcheck_import, task_engine_set, and proxy_toggle_intercept in every mode; it never downgrades a block to a prompt.

Operator approvals

When a call needs approval, the Approvals tab shows a card (and a dismissible popup) with the tool, targets, and arguments:

• Permission prompt: Allow once, Allow for session, or Deny with a reason.
• Out of scope: Add to scope (adds the origin to Burp's target scope for the project), Allow once, Allow for session, or Deny with a reason.

The decision (including the deny reason) is returned to the agent harness. "Allow for session" grants last until the extension is reloaded or the grants are cleared in the Approvals tab. The gated call waits approval_wait_seconds for a decision; if nobody answers it returns -32008 APPROVAL_PENDING and the agent retries the same call, so nothing executes after the client has stopped waiting. Pending requests expire after approval_ttl_seconds.

Target-scope enforcement covers the traffic-sending tools (http_send_request, http_send_requests, logger_add, scanner_start_audit, scanner_start_crawl). It defaults to prompt: out-of-scope traffic waits for the operator. If Burp's target scope is empty, every target counts as out-of-scope. Set scope_enforcement=deny to refuse out-of-scope calls with -32010 and no dialog, or off to disable the check. BURP_MCP_SCOPE_ENFORCEMENT=off does the same for automation. Redirect hops are not pre-checked, and the scanner follows Burp's own scope rules once seeded.

http_send_to_* staging tools and other non-sending tools are not scope-gated. Scanner and crawler tools generate real traffic against the target.

Configuration

Burp stores these in extension preferences, so they survive restarts. The Settings tab exposes all of them with JSON export/import. Exports omit auth_token and tls_keystore_password.

Environment variables win over stored preferences:

BURP_MCP_PORT=4444
BURP_MCP_BIND_ADDRESS=127.0.0.1
BURP_MCP_AUTH_TOKEN=secret
BURP_MCP_LOG_LEVEL=INFO
BURP_MCP_SOCKET_PATH=/tmp/burp-proj-a.sock
BURP_MCP_SCOPE_ENFORCEMENT=off
BURP_MCP_APPROVAL_WAIT_SECONDS=30
BURP_MCP_APPROVAL_TTL_SECONDS=300

Bad values are logged at startup as Invalid config: .... An empty token with auth_enabled=true blocks serving.

Health, logs, and limits

Auth is a single Bearer token:

mcp_servers:
  burp:
    url: https://127.0.0.1:4444
    headers:
      Authorization: Bearer <token>

TLS is off by default. Set tls_enabled=true, then self_signed for local work or custom with a PKCS12 keystore; custom without a path fails at startup.

curl http://127.0.0.1:4444/health
curl http://127.0.0.1:4444/health?format=prometheus

Health stays unauthenticated so monitoring can poll it.

Inbound bodies cap at 10 MB and tool output truncates at max_response_body_bytes. Rate limiting is per socket IP, and X-Forwarded-For is ignored because clients can spoof it. The connection cap returns 503 with -32007. Tools that call outside Burp get a circuit breaker: five failures in 60 seconds open it for 30 seconds, then one probe decides whether to close it.

Logs are JSON lines with a correlation ID per call, filtered by log_level; the file copy rotates at 5 MB and keeps three backups.

Errors come back as JSON-RPC codes:

A malformed Content-Length or truncated body returns 400, not 500.

The Status tab has Start, Stop, and Restart. Restart re-reads saved settings, so port, bind address, TLS, socket, and pool changes apply without reloading the extension.

Troubleshooting

Development

mvn clean compile
mvn test                      # 180 unit and mocked-transport tests
mvn clean package -DskipTests

No Maven wrapper is checked in. Tests use JUnit 5 and AssertJ, and the integration suite starts a real NanoHTTPD on a random port.

LiveBurpIT is excluded from normal runs and needs Burp with the extension loaded:

BURP_MCP_TEST_BASE_URL=http://127.0.0.1:4444 mvn test -Dtest=LiveBurpIT

Optional: BURP_MCP_TEST_AUTH_TOKEN for a Bearer token, BURP_MCP_TEST_ALLOW_SCANS=1 to include the crawl test on Professional. The suite starts its own loopback targets, cleans up the scope subtree it uses, backs off on 429, and skips when Burp is unreachable.

Conventions and project layout are in AGENTS.md.

Security

The server binds to loopback by default. Opening bind_address to 0.0.0.0 without auth or TLS exposes Burp to your network. The tools act with your Burp session's access, so treat an MCP client like any other operator at your keyboard. Use Read-Only mode and the sensitivity switch for passive work, or Prompt mode plus scope enforcement to review writes and out-of-scope traffic before they run.

License

MIT