nodriver-proxy-mcp

<p align="center"> <h1 align="center">nodriver-proxy-mcp</h1> <p align="center"> <strong>Give your AI agent a browser, a proxy, and a Python sandbox.</strong><br/> It navigates like a human, intercepts like Burp, and codes its own exploits on the fly. </p> <p align="center"> <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.10+-3776AB.svg?logo=python&logoColor=white" alt="Python 3.10+"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-8A2BE2" alt="MCP"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a> </p> </p>

한국어

---

Why this exists

Existing security MCP servers give the AI read-only access to traffic or just wrap CLI tools. This one gives full, autonomous control: the agent opens a browser that bypasses bot detection, captures every request through a MITM proxy, and when the built-in tools aren't enough, it writes and runs its own Python to chain everything together.

"Scan target.com for IDOR vulnerabilities"

  1. Agent starts proxy + browser
  2. Navigates to login page, types credentials, clicks submit
  3. Captures the auth flow, extracts the JWT
  4. Replays API requests with different user IDs
  5. Writes a Python script to automate the full IDOR check
  6. Reports which endpoints are vulnerable

No human touches the keyboard. The agent does it all through 39 MCP tools.

---

Why pentesters should care

What can it do that Burp / ZAP can't?

	Burp Suite / ZAP	nodriver-proxy-mcp
Who drives?	You click manually	AI does everything autonomously
Bot detection	Blocked by Cloudflare, DataDome, etc.	Bypasses automatically (nodriver)
Scripting	Write extensions / macros yourself	AI writes Python scripts on the fly, with access to all 38 tools via SDK
Client-side data	Not visible	Reads localStorage, sessionStorage, JS console, DOM hidden inputs
Can they work together?	—	Yes — chain through Burp with upstream="localhost:8080"

What can it do that other security MCP servers can't?

Most security MCP servers just wrap curl or read-only traffic viewers. This one has:

• Real mitmproxy — full traffic recording, replay, fuzzing, interception rules, session variables. Not a simplified HTTP client.
• Two ways to modify traffic — browser-level (instant, CDP Fetch) or proxy-level (system-wide, all HTTP clients). Other MCPs offer neither.
• Code-mode with SDK — the AI writes a Python script that runs in a sandbox, calling 29 tools in loops with asyncio. Race conditions, blind SQLi, and brute-force that would take thousands of MCP round-trips finish in seconds.

What it's great at

Use case	How the agent handles it
IDOR	Opens two browser sessions (victim + attacker), extracts tokens, replays requests swapping user IDs in a loop
XSS	Types payloads into inputs, clicks submit, checks if alert() dialog fires. Inspects DOM for injection points.
Auth bypass	Scans traffic to detect JWT / API key / session cookie patterns, extracts tokens, replays with modifications
API testing	Captures all API calls, searches by keyword/status, replays with regex replacement, fuzzes with anomaly detection
Race conditions	Code-mode sends 50+ concurrent requests via asyncio.gather() with precise timing
Blind SQLi	Code-mode runs binary search extraction — hundreds of conditional requests with logic between each one
CSP bypass	Intercepts responses at browser level, strips or modifies Content-Security-Policy header before Chrome enforces it

---

Architecture

Overall system

graph TB
    Agent["🤖 AI Agent<br/>(Claude, Cursor, etc.)"]

    subgraph MCP["MCP Server Process"]
        direction LR
        PT["Proxy Tools<br/>18 tools"]
        BT["Browser Tools<br/>20 tools"]
        CT["Code-mode<br/>1 tool"]
    end

    subgraph Proxy["mitmproxy :8082"]
        Addon["Addon Script<br/>record + intercept"]
        DB[("SQLite<br/>traffic.db")]
        Addon -->|write| DB
    end

    subgraph BrowserSession["BrowserDaemon (per session)"]
        Chrome["Chrome<br/>nodriver (anti-bot)"]
        Fetch["CDP Fetch<br/>intercept hooks"]
        Chrome --- Fetch
    end

    subgraph Sandbox["Code-mode Sandbox"]
        Script["AI-generated<br/>Python script"]
        SDK["NdpSDK<br/>29 methods"]
        Script --> SDK
    end

    Target[("🎯 Target")]

    Agent <-->|"stdio JSON-RPC"| MCP
    PT --> Proxy
    BT -->|"TCP IPC<br/>JSON-RPC"| BrowserSession
    CT -->|"subprocess<br/>fork+exec"| Sandbox

    Chrome -->|"all traffic routed"| Proxy
    Proxy <-->|"HTTP/S"| Target

    SDK -.->|"direct read/write"| DB
    SDK -.->|"TCP IPC"| BrowserSession

Two interception layers

graph LR
    subgraph Layer1["Layer 1 — CDP Fetch (instant)"]
        direction LR
        C1["Chrome"] -->|"request"| F1["Fetch API<br/>inject header / block"]
        F1 -->|"modified"| P1["→ mitmproxy"]
        P2["mitmproxy →"] -->|"response"| F2["Fetch API<br/>replace body / block"]
        F2 -->|"modified"| C2["→ Chrome"]
    end

    subgraph Layer2["Layer 2 — mitmproxy (system-wide)"]
        direction LR
        Any["Any HTTP client"] --> M1["mitmproxy<br/>inject header / replace body / block"]
        M1 --> T2["→ Target"]
    end

    style Layer1 fill:#1a1a2e,stroke:#3fb950,color:#e6edf3
    style Layer2 fill:#1a1a2e,stroke:#58a6ff,color:#e6edf3

CDP Fetch = browser-only, instant, per-session. mitmproxy rules = all traffic, ~5s cache delay, system-wide.

Process lifecycle

Process	Parent	IPC method	Auto-cleanup
mitmproxy	MCP server	SQLite (shared file)	Watchdog thread kills on parent death; stderr drain prevents pipe hang
BrowserDaemon	MCP server	TCP JSON-RPC (dynamic port)	Parent PID watch → IPC close → SIGTERM → SIGKILL
Chrome	BrowserDaemon	CDP (Chrome DevTools Protocol)	browser.stop() on daemon exit
Code-mode script	MCP server	Env vars (ports, sessions)	Job Object / killpg; 256MB RAM, 60s CPU

---

NdpSDK — Code-mode Python SDK

NdpSDK is a Python wrapper that exposes the same 38 tools (proxy + browser) as async methods, designed for use inside execute_security_code. When the AI needs loops, concurrency, or multi-step logic that would be impractical as individual MCP calls, it writes a script using NdpSDK instead.

from nodriver_proxy_mcp.sdk import NdpSDK
import asyncio

async def main():
    sdk = NdpSDK()  # auto-discovers running proxy + browser sessions

    flows = await sdk.get_traffic_summary(limit=20)
    await sdk.browser_go("https://target.com/admin")

    # Loops — this is why NdpSDK exists
    for uid in range(1, 100):
        resp = await sdk.replay_flow(
            flow_id,
            replacements=[{"regex": r"/users/\d+", "replacement": f"/users/{uid}"}]
        )
        if resp["status_code"] == 200:
            print(f"IDOR: /users/{uid}")

asyncio.run(main())

---

Quick start

1. Install

pip install nodriver-proxy-mcp

Or from source:

git clone https://github.com/BobongKu/nodriver-proxy-mcp.git
cd nodriver-proxy-mcp
pip install .

2. Add to your AI agent

MCP clients (mcp_config.json):

{
  "mcpServers": {
    "nodriver-proxy-mcp": {
      "command": "nodriver-proxy-mcp"
    }
  }
}

3. Use it

Just tell your AI agent what to do. The tools are self-descriptive — the agent picks the right ones automatically.

---

All 39 tools

Proxy (18)

Tool	Purpose
manage_proxy	Start/stop mitmproxy. Chain to Burp via upstream. GUI via ui=True.
proxy_status	Check running state, port, PID
set_scope	Limit recording to specific domains
get_traffic_summary	Paginated flow list with IDs, URLs, methods, status codes
inspect_flow	Full request/response details — headers, body, metadata
search_traffic	Filter by keyword, domain, method, status code
extract_from_flow	Pull values via JSONPath, regex, or CSS selectors
extract_session_variable	Save a value for {{placeholder}} reuse in replay
list_session_variables	Show all extracted variables
generate_curl	Export a flow as a copy-paste curl command
replay_flow	Resend with regex replacements + {{var}} substitution (like Burp Repeater)
send_raw_request	Craft arbitrary HTTP requests from raw text (SSRF-protected)
add_interception_rule	Live proxy traffic manipulation: inject headers, replace body, block
list_interception_rules	Show active proxy rules
remove_interception_rule	Delete a proxy rule by ID
detect_auth_pattern	Auto-detect JWT, Bearer, API key, session cookie, CSRF, OAuth2
fuzz_endpoint	Concurrent fuzzing with baseline anomaly detection
clear_traffic	Wipe the traffic database

Browser (20)

Tool	Purpose
browser_open / browser_close	Launch or kill a Chrome session (anti-bot bypass, headless by default)
browser_list_sessions	Active sessions with PID, ports, uptime
browser_list_tabs	Tabs in a session
browser_go / browser_back	Navigate, wait for page load, SPA support via wait_for
browser_click	Click by CSS selector or visible text. Returns JS alert dialogs (XSS detection).
browser_type	Type into inputs — login forms, search boxes, payload injection
browser_get_dom	Security-focused DOM: forms, scripts, iframes, comments, event handlers, data-* attributes
browser_get_text	Text content from any CSS selector
browser_get_storage	Dump localStorage + sessionStorage (invisible to proxy)
browser_get_console	JS console output — stack traces, debug URLs, CSP violations
browser_screenshot	Capture page as PNG — bot challenges, evidence, state verification
browser_set_cookie	Set cookies via CDP (supports httpOnly — unlike document.cookie)
browser_js	Execute arbitrary JavaScript in page context
browser_wait	Wait for element/text to appear (SPA/AJAX support)
browser_intercept_request	CDP Fetch: inject headers, block outgoing requests (instant)
browser_intercept_response	CDP Fetch: replace response body, block responses (instant)
browser_intercept_disable	Turn off all CDP Fetch interception
browser_list_intercept_rules	Show active CDP Fetch rules

Code-mode (1)

Tool	Purpose
execute_security_code	Run AI-generated Python with NdpSDK — programmatic access to all 38 other tools. Sandboxed.

---

Burp Suite integration

Use upstream to chain mitmproxy through Burp for manual analysis alongside AI automation:

manage_proxy(action="start", upstream="localhost:8080")

Traffic flows: Chrome --> mitmproxy (:8082) --> Burp Suite (:8080) --> Target

Both tools see the same traffic. The AI automates; you analyze in Burp when you need to.

---

Workflow — IDOR sweep with code-mode

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant Proxy as mitmproxy
    participant Browser as Chrome (nodriver)
    participant Code as Code-mode (NdpSDK)
    participant Target as Target

    Note over Agent,Target: Phase 1 - Setup
    Agent->>MCP: manage_proxy(start)
    MCP->>Proxy: launch :8082
    Agent->>MCP: browser_open(proxy_port=8082)
    MCP->>Browser: launch Chrome via proxy

    Note over Agent,Target: Phase 2 - Recon
    Agent->>MCP: browser_go(target.com)
    Browser->>Proxy: all traffic captured
    Proxy->>Target: GET /login, /api/*, /mypage...
    Target-->>Browser: responses
    Agent->>MCP: get_traffic_summary()
    MCP-->>Agent: 47 flows captured
    Agent->>MCP: detect_auth_pattern()
    MCP-->>Agent: Bearer token detected

    Note over Agent,Target: Phase 3 - Attack Surface Mapping
    Agent->>MCP: search_traffic("/api/")
    MCP-->>Agent: /api/users/me, /api/orders/1042, /api/profile/317
    Agent->>MCP: extract_session_variable(token)
    MCP-->>Agent: saved as my_token
    Note right of Agent: Found 3 endpoints with ID params

    Note over Agent,Target: Phase 4 - Code-mode IDOR Sweep
    Agent->>MCP: execute_security_code(script)
    MCP->>Code: fork + sandbox

    loop every endpoint x ID 1~100
        Code->>Target: GET /api/users/[id] + my_token
        Target-->>Code: 200 with other user data / 403
        Code->>Target: GET /api/orders/[id] + my_token
        Target-->>Code: 200 with other order data / 403
        Code->>Target: GET /api/profile/[id] + my_token
        Target-->>Code: 200 with other profile / 403
    end

    Code-->>MCP: results summary
    MCP-->>Agent: /api/users: 100/100 accessible, /api/orders: 38/100, /api/profile: 0/100

---

Troubleshooting

Problem	Fix
Browser won't launch	Install Chrome/Chromium. nodriver requires a real Chrome binary.
SSL certificate errors	Trust the mitmproxy CA: ~/.mitmproxy/mitmproxy-ca-cert.pem
Port already in use	manage_proxy(port=XXXX) — or restart, orphaned processes are auto-killed
Tools not showing	Restart your Claude Code / Cursor session to reload the MCP server
uvx doesn't work	Don't use uvx. Clone the repo and use uv run --directory instead.

---

License

MIT