# Burp Suite MCP Server

An MCP (Model Context Protocol) server that exposes Burp Suite's REST API as tools for AI assistants. Use Cursor or other MCP clients to trigger vulnerability scans, check progress, and query Burp's security knowledge base.

## Prerequisites

- **Burp Suite Professional** (or Burp Suite DAST) with the REST API enabled
- **Python 3.11+**
- Burp running locally with REST API bound to a reachable address (e.g. `http://127.0.0.1:1337`)

## Setup

### 1. Enable Burp REST API

1. Open Burp Suite → **Settings** → **Suite** → **REST API**
2. Check **Service running**
3. Set the URL/port (e.g. port `1337`)
4. Create an API key and copy it

### 2. Install the MCP server

```bash
uv sync   # or: pip install -e .
```

### 3. Configure environment

Copy `.env.example` to `.env` and fill in your values:

```bash
cp .env.example .env
```

Edit `.env`:

```
BURP_REST_API_BASE=http://127.0.0.1:1337
BURP_REST_API_KEY=your-api-key-here
BURP_REST_API_VERSION=v0.1
```

## Transport modes

The server supports three transports, selected with `--transport`:

| Flag | Transport | Use case |
|------|-----------|----------|
| `--transport stdio` | stdio (default) | Local MCP clients (Cursor, Claude Desktop) |
| `--transport sse` | Server-Sent Events | HTTP clients using the legacy SSE protocol |
| `--transport http` | Streamable HTTP | HTTP clients using the modern MCP HTTP protocol |

For `sse` and `http`, bind address and port are configurable:

```bash
# Default: localhost only, port 8000
uv run python main.py --transport http

# Expose on all interfaces, custom port
uv run python main.py --transport http --host 0.0.0.0 --port 9000

# SSE transport
uv run python main.py --transport sse --host 127.0.0.1 --port 8000
```

## Cursor MCP Configuration

### stdio (local process)

Add to your Cursor MCP config (e.g. `~/.cursor/mcp.json` or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "burp-suite": {
      "command": "uv",
      "args": ["run", "python", "/path/to/burp-mcp/main.py"],
      "cwd": "/path/to/burp-mcp"
    }
  }
}
```

### HTTP (remote/shared server)

Start the server with HTTP transport, then point your MCP client at it:

```bash
uv run python main.py --transport http --host 0.0.0.0 --port 8000
```

```json
{
  "mcpServers": {
    "burp-suite": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `burp_suite_security_issue_definitions` | Get Burp's security issue definitions (name, description, remediation, references) |
| `scan_urls_for_vulnerabilities` | Start a scan for given URLs. Returns a `task_id` for tracking. Optional `scope` param |
| `check_security_scan_progress` | Get scan status and findings by `task_id`. Filter by severity: `low`, `info`, `medium`, `high`, or `all` |
| `get_scan_summary` | High-level summary: total issues by severity |
| `list_active_scans` | List running/pending scans (may not be supported by all Burp API versions) |
| `cancel_scan` | Cancel a scan by task_id (may not be supported by all Burp API versions) |
| `check_burp_connectivity` | Test connectivity to Burp API; validates config |
| `wait_for_scan_completion` | Poll until scan completes or times out (for CI/CD) |

## Usage Examples

**Scan a URL:**
> "Scan https://example.com for vulnerabilities"

**Check scan progress:**
> "Check scan progress for task_id 123"

**Get high-severity issues only:**
> "Check scan 123 and show only high severity issues"

**Security knowledge:**
> "What security issues does Burp know about?"

## Command-line usage

Run scans from scripts or the terminal:
```bash
uv run python examples/ci-scan.py https://your-target.com
# or
./examples/ci-scan.sh https://your-target.com
```

## Burp REST API Endpoints Used

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/knowledge_base/issue_definitions` | GET | Security issue definitions |
| `/scan` | POST | Start scan (body: `{"urls": [...]}`) |
| `/scan` | GET | List scans (may not be supported) |
| `/scan/{task_id}` | GET | Scan progress and results |
| `/scan/{task_id}` | DELETE | Cancel scan (may not be supported) |

Interactive API docs: `[BURP_REST_API_BASE]/[API_KEY]`

## License

MIT