nodriver-proxy-mcp
Allows routing all proxy traffic through Burp Suite as an upstream proxy, enabling interception and analysis with Burp's tools while maintaining the MCP server's browser automation and code execution capabilities.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nodriver-proxy-mcp Scan target.com for IDOR vulnerabilities"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 vulnerableNo human touches the keyboard. The agent does it all through 39 MCP tools.
Related MCP server: Security Hunter MCP
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 |
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 |
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 |
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"| BrowserSessionTwo 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:#e6edf3CDP 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) |
|
Code-mode script | MCP server | Env vars (ports, sessions) | Job Object / |
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-mcpOr 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 |
| Start/stop mitmproxy. Chain to Burp via |
| Check running state, port, PID |
| Limit recording to specific domains |
| Paginated flow list with IDs, URLs, methods, status codes |
| Full request/response details — headers, body, metadata |
| Filter by keyword, domain, method, status code |
| Pull values via JSONPath, regex, or CSS selectors |
| Save a value for |
| Show all extracted variables |
| Export a flow as a copy-paste curl command |
| Resend with regex replacements + |
| Craft arbitrary HTTP requests from raw text (SSRF-protected) |
| Live proxy traffic manipulation: inject headers, replace body, block |
| Show active proxy rules |
| Delete a proxy rule by ID |
| Auto-detect JWT, Bearer, API key, session cookie, CSRF, OAuth2 |
| Concurrent fuzzing with baseline anomaly detection |
| Wipe the traffic database |
Browser (20)
Tool | Purpose |
| Launch or kill a Chrome session (anti-bot bypass, headless by default) |
| Active sessions with PID, ports, uptime |
| Tabs in a session |
| Navigate, wait for page load, SPA support via |
| Click by CSS selector or visible text. Returns JS alert dialogs (XSS detection). |
| Type into inputs — login forms, search boxes, payload injection |
| Security-focused DOM: forms, scripts, iframes, comments, event handlers, |
| Text content from any CSS selector |
| Dump localStorage + sessionStorage (invisible to proxy) |
| JS console output — stack traces, debug URLs, CSP violations |
| Capture page as PNG — bot challenges, evidence, state verification |
| Set cookies via CDP (supports httpOnly — unlike document.cookie) |
| Execute arbitrary JavaScript in page context |
| Wait for element/text to appear (SPA/AJAX support) |
| CDP Fetch: inject headers, block outgoing requests (instant) |
| CDP Fetch: replace response body, block responses (instant) |
| Turn off all CDP Fetch interception |
| Show active CDP Fetch rules |
Code-mode (1)
Tool | Purpose |
| Run AI-generated Python with |
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/100Troubleshooting
Problem | Fix |
Browser won't launch | Install Chrome/Chromium. |
SSL certificate errors | Trust the mitmproxy CA: |
Port already in use |
|
Tools not showing | Restart your Claude Code / Cursor session to reload the MCP server |
| Don't use |
License
MIT
Available Tools
39 toolsadd_interception_ruleA
Add a rule that modifies HTTP traffic in real-time as it passes through the mitmproxy.
PREREQUISITE: Proxy must be running (call manage_proxy(action="start") first).
NOTE: These rules apply to ALL traffic through the proxy (browser + code-mode + replay). Rules are cached for ~5 seconds, so changes are not instant. For instant browser-only interception, use browser_intercept_request/response instead.
Available actions:
"inject_header": Add/override a header. Requires key and value. Example: add_interception_rule(url_pattern=".api.", action="inject_header", key="X-Admin", value="true")
"replace_body": Find and replace text in the body. Requires search_pattern and value. Example: add_interception_rule(url_pattern=".*", action="replace_body", search_pattern="false", value="true", resource_type="response")
"block": Block matching requests entirely. Example: add_interception_rule(url_pattern=".analytics.", action="block")
Args: url_pattern: Regex pattern to match URLs (e.g. ".api.target.com.", ".*.js$") action: "inject_header", "replace_body", or "block" resource_type: "request" or "response" (default: "request") key: Header name (required for inject_header only) value: Header value (for inject_header) or replacement text (for replace_body) search_pattern: Regex to find in body (required for replace_body only) method: Only match this HTTP method, e.g. "POST" (optional, matches all methods if omitted)
Inputs: action (required), url_pattern (required), key, value, +3 more. Returns: result
browser_backA
Navigate back in browser history (like clicking the Back button).
PREREQUISITE: browser_open and browser_go must have been called first.
Args: session_name: Browser session to use (default: "default")
Inputs: tab_id, session_name. Returns: result
browser_clickA
Click an element on the page. Returns any JavaScript alert/confirm/prompt dialog messages triggered.
PREREQUISITE: browser_open and browser_go must have been called first.
Provide EITHER selector OR text (not both):
selector: CSS selector for the element (e.g. "#login-btn", "button[type=submit]")
text: Visible text to find and click (uses best match, e.g. "Login", "Submit")
XSS DETECTION: If clicking triggers a JavaScript alert() dialog, the dialog message is returned. This is how you verify reflected/stored XSS — inject a payload, navigate to the page, and check for alerts.
Args: selector: CSS selector to click (e.g. "#submit", "button.login") text: Visible text to find and click (e.g. "Login", "Submit Order") session_name: Browser session to use (default: "default")
Inputs: text, tab_id, selector, session_name. Returns: result
browser_closeA
Close a browser session and terminate the Chrome process.
Call this when you're done with a browser session to free resources. If session_name is omitted, closes the "default" session.
Args: session_name: Session to close (default: "default")
Inputs: session_name. Returns: result
browser_get_consoleA
Read JavaScript console output from the browser. Returns data the PROXY CANNOT SEE.
PREREQUISITE: browser_open and browser_go must have been called first.
Console messages often contain:
Stack traces that reveal internal file paths and function names
Debug messages with internal API URLs or configuration
Error messages that indicate vulnerability surfaces
Content Security Policy (CSP) violation reports
Args: level: Filter by message level — "all" (default), "error", or "warning" clear: Clear the console buffer after reading (default false). Set true to avoid re-reading old messages. session_name: Browser session to use (default: "default")
Inputs: clear, level, tab_id, session_name. Returns: result
browser_get_domA
Extract security-relevant DOM structure from the current page. Returns data the PROXY CANNOT SEE.
PREREQUISITE: browser_open and browser_go must have been called first.
Automatically extracts:
Forms: action URLs, methods, input fields, hidden inputs, CSRF tokens
Links: all href values
Scripts: src attributes (for finding JS endpoints)
Iframes: embedded frame sources
HTML comments: developers often leave sensitive info in comments
Event handlers: onclick, onsubmit, etc. (for client-side logic)
data-* attributes: often contain API endpoints or config values
Simplified DOM tree (depth-limited)
Use this for initial recon after navigating to a page.
Args: selector: Root element CSS selector to analyze (default: "body" = entire page) max_depth: How deep to traverse the DOM tree (default: 4). Higher = more detail but more tokens. session_name: Browser session to use (default: "default")
Inputs: tab_id, selector, max_depth, session_name. Returns: result
browser_get_storageA
Dump browser localStorage and/or sessionStorage contents. Returns data the PROXY CANNOT SEE.
PREREQUISITE: browser_open and browser_go must have been called first.
Web apps often store JWT tokens, API keys, user preferences, or feature flags in browser storage. This data never appears in HTTP traffic — it's only accessible client-side.
Args: storage_type: What to read — "local" (localStorage only), "session" (sessionStorage only), or "both" (default) session_name: Browser session to use (default: "default")
Inputs: tab_id, session_name, storage_type. Returns: result
browser_get_textA
Get the visible text content of a specific DOM element.
PREREQUISITE: browser_open and browser_go must have been called first.
Use this to read specific parts of a page (error messages, user info, API responses rendered in HTML). For full DOM analysis, use browser_get_dom instead.
Args: selector: CSS selector for the element (e.g. "#error-message", ".user-name", "h1") session_name: Browser session to use (default: "default")
Inputs: selector (required), tab_id, session_name. Returns: result
browser_goA
Navigate to a URL and wait for the page to load. Returns the page title and any JS dialog messages.
PREREQUISITE: browser_open must have been called first.
For Single Page Applications (SPAs) that load content dynamically after initial page load, use wait_for to specify a CSS selector that indicates the content is ready.
Args: url: Full URL to navigate to (e.g. "https://target.com/login") session_name: Browser session to use (default: "default") tab_id: Target a specific tab (optional — uses active tab if omitted) wait_for: CSS selector to wait for after navigation (e.g. "#main-content", ".login-form"). Use for SPAs.
Inputs: url (required), tab_id, wait_for, session_name. Returns: result
browser_intercept_disableA
Disable ALL CDP Fetch interception and remove all rules for this browser session.
Call this when you want to stop intercepting and return to normal browsing. This clears both request and response intercept rules.
Args: session_name: Browser session to use (default: "default")
Inputs: session_name. Returns: result
browser_intercept_requestA
Intercept and modify OUTGOING browser requests in real-time via Chrome CDP Fetch API.
PREREQUISITE: browser_open must have been called first.
IMPORTANT — This is DIFFERENT from add_interception_rule (proxy-level):
browser_intercept_* = instant, browser-only, via Chrome CDP. Changes take effect immediately.
add_interception_rule = proxy-level, ~5s cache delay, applies to ALL traffic (browser + code-mode).
Available actions:
"inject_header": Add a custom header to matching requests. Example: browser_intercept_request(url_pattern=".api.", action="inject_header", key="X-Admin", value="true")
"block": Block matching requests entirely (returns network error to the page). Example: browser_intercept_request(url_pattern=".analytics.", action="block")
Args: url_pattern: Regex pattern to match request URLs (e.g. ".api.target.com.") action: "inject_header" or "block" key: Header name (required for inject_header) value: Header value (required for inject_header) session_name: Browser session to use (default: "default")
Inputs: action (required), url_pattern (required), key, value, +1 more. Returns: result
browser_intercept_responseA
Intercept and modify INCOMING browser responses in real-time via Chrome CDP Fetch API.
PREREQUISITE: browser_open must have been called first.
USE CASES:
CSP bypass testing: Replace Content-Security-Policy headers in responses
Response tampering: Modify API responses to test client-side validation
Inject XSS payloads into response bodies
Remove security headers to test fallback behavior
Available actions:
"replace_body": Find and replace text in the response body. Example: browser_intercept_response(url_pattern=".api.", action="replace_body", search_pattern='"admin":false', value='"admin":true')
"block": Block the response entirely.
Args: url_pattern: Regex pattern to match request URLs (e.g. ".api.target.com/me.") action: "replace_body" or "block" search_pattern: Regex to find in the response body (required for replace_body) value: Replacement text (required for replace_body) session_name: Browser session to use (default: "default")
Inputs: action (required), url_pattern (required), value, session_name, +1 more. Returns: result
browser_jsA
Execute arbitrary JavaScript in the browser page context. Returns the expression's result.
PREREQUISITE: browser_open and browser_go must have been called first.
USE CASES:
Extract CSRF tokens: 'document.querySelector("meta[name=csrf-token]").content'
Read cookies: 'document.cookie'
Hook fetch API to monitor requests
Inspect JavaScript objects and prototypes
Test DOM-based XSS payloads
Call internal JavaScript functions
The expression is evaluated in the page's JS context — it has full access to the page's DOM, variables, functions, and APIs.
Args: expression: JavaScript code to evaluate. Can be a single expression or multi-line code. Example: 'document.title' or 'fetch("/api/me").then(r=>r.json())' session_name: Browser session to use (default: "default")
Inputs: expression (required), tab_id, session_name. Returns: result
browser_list_intercept_rulesA
List all active CDP Fetch interception rules for a browser session.
NOTE: These are browser-level rules only (set via browser_intercept_request/response). For proxy-level rules, use list_interception_rules instead.
Args: session_name: Browser session to use (default: "default")
Inputs: session_name. Returns: result
browser_list_sessionsA
List all active browser sessions with their status, PID, ports, and uptime.
Use this to check which sessions are running before sending commands. Dead sessions are automatically cleaned up.
Inputs: no named parameters. Returns: result
browser_list_tabsA
List all open tabs in a browser session with their tab IDs and URLs.
PREREQUISITE: browser_open must have been called first.
Use tab_id from the results to target specific tabs in other browser_* tools.
Args: session_name: Browser session to query (default: "default")
Inputs: session_name. Returns: result
browser_openA
Launch a new Chrome browser session with anti-bot bypass (nodriver CDP). Call this BEFORE any other browser_* tool.
TYPICAL STARTUP SEQUENCE:
manage_proxy(action="start") — start the proxy first
browser_open(proxy_port=8082) — launch Chrome routed through proxy
browser_go(url="https://target.com") — navigate
Each session is an independent Chrome instance. You can run multiple sessions simultaneously for multi-user testing (e.g. "victim" and "attacker" sessions for IDOR/privilege escalation).
The browser uses nodriver which bypasses Cloudflare, DataDome, and other bot detection automatically.
Args: session_name: Unique name for this session (default: "default"). Use different names for multiple sessions. proxy_port: Route all browser traffic through mitmproxy on this port (default 8082). Must match the port used in manage_proxy. Set to 0 to disable proxy routing. headless: Run Chrome without a visible window (default true). Set false for visual debugging.
Inputs: headless, proxy_port, session_name. Returns: result
browser_screenshotA
Take a screenshot of the current page (returns base64-encoded PNG).
PREREQUISITE: browser_open and browser_go must have been called first.
Useful for:
Verifying the page state after navigation (did login succeed?)
Checking for bot detection challenges (Cloudflare, CAPTCHA)
Documenting vulnerability evidence
Visual confirmation before destructive actions
Args: selector: CSS selector to capture a specific element (optional — captures full page if omitted) session_name: Browser session to use (default: "default")
Inputs: tab_id, selector, session_name. Returns: result
browser_set_cookieA
Set a cookie in the browser via CDP. Can set httpOnly cookies (unlike document.cookie in JS).
PREREQUISITE: browser_open and browser_go must have been called first (need a page loaded for domain).
USE CASES:
IDOR testing: Set another user's session cookie to test access controls
Session fixation: Pre-set a known session ID
Testing httpOnly bypass: Inject cookies that JavaScript can't normally set
Args: name: Cookie name (e.g. "session_id", "auth_token") value: Cookie value domain: Cookie domain (default: current page's domain). Must match or be a parent of the page domain. path: Cookie path (default: "/") http_only: Set the HttpOnly flag — makes cookie invisible to document.cookie (default false) secure: Set the Secure flag — cookie only sent over HTTPS (default false) session_name: Browser session to use (default: "default")
Inputs: name (required), value (required), path, domain, +4 more. Returns: result
browser_typeA
Type text into an input field (login forms, search boxes, payload injection).
PREREQUISITE: browser_open and browser_go must have been called first.
TYPICAL LOGIN FLOW:
browser_go(url="https://target.com/login")
browser_type(selector="#email", text="admin@target.com")
browser_type(selector="#password", text="password123")
browser_click(selector="#login-btn")
For XSS testing, type payloads directly: browser_type(selector="#search", text='alert(1)')
Args: selector: CSS selector for the input element (e.g. "#email", "input[name=username]", "#search") text: Text to type. Can be any string including XSS/SQLi payloads. clear: Clear existing text before typing (default true). Set false to append. press_enter: Press Enter key after typing (default false). Useful for search forms without a submit button. session_name: Browser session to use (default: "default")
Inputs: text (required), selector (required), clear, tab_id, +2 more. Returns: result
browser_waitA
Wait for a DOM element or text to appear on the page. Use for SPAs, AJAX, and dynamic content.
PREREQUISITE: browser_open and browser_go must have been called first.
Use this AFTER browser_go or browser_click when the page loads content asynchronously. Provide EITHER selector OR text (not both).
Args: selector: CSS selector to wait for (e.g. "#dashboard", ".search-results", "table.data") text: Text content to wait for (e.g. "Welcome back", "Results found") timeout: Maximum wait time in seconds (default: 10). Returns error if element doesn't appear. session_name: Browser session to use (default: "default")
Inputs: text, tab_id, timeout, selector, +1 more. Returns: result
clear_trafficA
Delete all captured traffic from the database. Use when you want a clean slate before a new test.
WARNING: This permanently deletes all recorded flows. Session variables are NOT cleared.
Inputs: no named parameters. Returns: result
detect_auth_patternA
Automatically scan captured traffic to detect authentication mechanisms.
PREREQUISITE: Proxy must be running and have captured traffic (especially login/API flows).
Detects: JWT, Bearer tokens, API keys, session cookies, CSRF tokens, Basic auth, OAuth2 endpoints. Returns which auth types were found and the flow IDs where they appear.
Use this early in a pentest to understand the target's auth model before planning attacks.
Args: flow_ids: Optional comma-separated flow IDs to analyze (e.g. "abc123,def456"). If omitted, scans the 100 most recent flows automatically.
Inputs: flow_ids. Returns: result
execute_security_codeA
Execute a Python script in an isolated sandbox with full access to all other tools via NdpSDK.
REQUIRES: approved=true (human must approve arbitrary code execution).
WHEN TO USE THIS (instead of individual tools):
Race conditions / TOCTOU attacks (need precise timing)
Blind SQL injection (needs hundreds of sequential requests with conditional logic)
Multi-step exploit chains (login → extract token → IDOR scan → report)
Heavy loops (brute force, enumeration)
Complex encoding/decoding chains (double URL encoding, JWT manipulation)
Custom PoC/exploit generation
HOW TO USE NdpSDK:
from nodriver_proxy_mcp.sdk import NdpSDK
import asyncio
async def main():
sdk = NdpSDK() # auto-connects to running proxy and browser sessions
# All 38 other tools are available as async methods:
await sdk.manage_proxy("start")
await sdk.browser_open()
await sdk.browser_go("https://target.com")
flows = await sdk.get_traffic_summary()
result = await sdk.replay_flow(flow_id, replacements=[...])
asyncio.run(main())RESOURCE LIMITS: 256MB memory, 60s CPU time, 32KB output cap. External packages can be auto-installed via the dependencies parameter.
Args: script_content: Python code to execute. Use NdpSDK to access all proxy/browser tools programmatically. dependencies: Pip packages to install before execution (e.g. ["pyjwt", "pycryptodome", "beautifulsoup4"]). timeout: Maximum wall-clock execution time in seconds (default: 300 = 5 minutes). approved: MUST be true. Set this ONLY after the human user has explicitly approved code execution. bypass_proxy: If true, HTTP requests from the script skip the proxy (for raw speed or avoiding interception loops).
Inputs: script_content (required), timeout, approved, bypass_proxy, +1 more. Returns: result
extract_from_flowA
Extract specific data from a flow's response body using JSONPath, CSS selector, or regex.
PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic.
Choose exactly ONE extractor per call:
json_path: For JSON API responses. Example: "$.data.users[0].id"
css_selector: For HTML pages. Example: "input[name=csrf]" to find CSRF tokens
regex: For any text. Example: 'token":"([^"]+)' to capture a token value
To save the extracted value for reuse in replay_flow, use extract_session_variable instead.
Args: flow_id: The flow ID to extract from json_path: JSONPath expression (e.g. "$.data.users[0].id", "$.token") css_selector: CSS selector for HTML (e.g. "input[name=csrf]", "a.secret-link") regex: Regex pattern — use capture groups to extract specific parts (e.g. 'token":"([^"]+)')
Inputs: flow_id (required), regex, json_path, css_selector. Returns: result
extract_session_variableA
Extract a value from a captured flow and save it as a named session variable.
PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic.
Saved variables are automatically substituted in replay_flow: Any {{varname}} in the URL, headers, or body of a replayed request is replaced with the saved value.
TYPICAL AUTH WORKFLOW:
search_traffic(query="/login") → find the login response flow_id
extract_session_variable(flow_id, regex='token":"([^"]+)', name="jwt", source="response_body")
replay_flow(another_flow_id) → {{jwt}} in Authorization header is auto-replaced
Args: flow_id: The flow to extract from regex: Regex with exactly ONE capture group — the captured group becomes the saved value. Example: 'Bearer ([\w.-]+)' captures the token part only. name: Variable name to save as. Used as {{name}} in replay_flow. source: Where to extract from (default: "response_body"): - "response_body" — response body text - "response_header" — response headers (raw text) - "request_header" — request headers (raw text) - "request_body" — request body text
Inputs: name (required), regex (required), flow_id (required), source. Returns: result
fuzz_endpointA
Fuzz a captured HTTP request by injecting payloads and detecting anomalies.
REQUIRES: approved=true (human must approve high-volume fuzzing). PREREQUISITE: Get flow_id from a captured request that contains the target_pattern string.
HOW IT WORKS:
Takes the captured request and replaces target_pattern with each payload
Sends all modified requests (concurrently for speed)
Measures a baseline from the original request
Flags anomalies: unexpected status codes, unusual response lengths, latency spikes, error keywords
SETUP: Insert "FUZZ" into the target field before capturing:
For URL parameter fuzzing: browser_go("https://target.com/api?id=FUZZ")
For body fuzzing: use replay_flow with replacements first to insert FUZZ, then fuzz
Args: flow_id: The base flow to fuzz. Its URL/headers/body MUST contain the target_pattern string. payloads: List of strings to inject. Example: ["' OR 1=1--", "alert(1)", "../../../etc/passwd"] target_pattern: The placeholder string to replace with each payload (default: "FUZZ") concurrency: Number of simultaneous requests (default 5). Higher = faster but more aggressive. approved: MUST be true. Set this ONLY after the human user has explicitly approved this action.
Inputs: flow_id (required), payloads (required), approved, concurrency, +1 more. Returns: result
generate_curlA
Generate a copy-paste curl command that reproduces a captured HTTP flow.
PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic.
Useful for:
Exporting requests to share with teammates
Testing in terminal outside the MCP environment
Importing into Burp Suite or Postman
Args: flow_id: The flow ID to generate a curl command for
Inputs: flow_id (required). Returns: result
get_traffic_summaryA
Get a paginated list of all captured HTTP flows. REQUIRES: proxy must be running and traffic must exist.
Returns flow IDs, URLs, methods, status codes, and latency for each flow. Use the returned flow_id values with inspect_flow, replay_flow, extract_from_flow, etc.
WORKFLOW: manage_proxy(start) → browser_open → browser_go → get_traffic_summary → inspect_flow(flow_id)
Args: limit: Maximum number of flows to return (default 20). Use smaller values to save tokens. offset: Number of flows to skip from the start (default 0). Use for pagination: offset=20 gets the next page.
Inputs: limit, offset. Returns: result
inspect_flowA
Get full details of a single HTTP flow (request headers, body, response headers, body).
PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic first.
By default returns only metadata (URL, method, status) to save tokens. Add fields to the include list to get headers and bodies.
Args: flow_id: The flow ID from get_traffic_summary or search_traffic results. include: List of fields to include. Options: - "metadata" (default) — URL, method, status code, latency - "requestHeaders" — all request headers - "requestBody" — request body content - "responseHeaders" — all response headers - "responseBody" — response body content Example: ["metadata", "requestHeaders", "responseBody"]
Inputs: flow_id (required), include. Returns: result
list_interception_rulesA
List all active proxy interception rules (added via add_interception_rule).
NOTE: These are proxy-level rules only. For browser-level CDP Fetch rules, use browser_list_intercept_rules instead.
Inputs: no named parameters. Returns: result
list_session_variablesA
List all saved session variables. These are used as {{name}} placeholders in replay_flow.
Variables are created by extract_session_variable. They persist until the proxy is restarted.
Inputs: no named parameters. Returns: result
manage_proxyA
Start or stop the mitmproxy background process. This is the FIRST tool you should call before any proxy/traffic operation.
WORKFLOW:
Call manage_proxy(action="start") to start the proxy
Then call browser_open(proxy_port=8082) to route browser traffic through it
Now all browser traffic is captured — use get_traffic_summary, search_traffic, etc.
To chain through Burp Suite: manage_proxy(action="start", upstream="localhost:8080") To get a web GUI: manage_proxy(action="start", ui=true) — opens mitmweb on port 8081
Args: action: "start" to launch mitmproxy, "stop" to kill it. No other values accepted. port: Proxy listen port (default 8082). Browser must connect to the same port. ui: If true, launches mitmweb (web GUI on port 8081) instead of headless mitmdump. upstream: Forward all traffic to an upstream proxy (e.g. "localhost:8080" for Burp Suite). Leave empty for direct connections.
Inputs: action (required), ui, port, upstream. Returns: result
proxy_statusA
Check if the mitmproxy process is currently running. Returns status, port, and PID.
Call this BEFORE any proxy operation if you're unsure whether the proxy is already running. If status is "not_running", call manage_proxy(action="start") first.
Inputs: no named parameters. Returns: result
remove_interception_ruleA
Remove a proxy interception rule by its ID.
PREREQUISITE: Get rule_id from list_interception_rules or the add_interception_rule response.
Args: rule_id: The rule ID to remove (e.g. "r-abc12345")
Inputs: rule_id (required). Returns: result
replay_flowA
Resend a captured HTTP request with optional modifications (like Burp Repeater).
PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic.
Session variable substitution: Any {{varname}} in URL, headers, or body is automatically replaced with the value saved by extract_session_variable. Use this for token rotation.
Regex replacements: Modify parts of the request using regex find-and-replace. Example: replacements=[{"regex": "user_id=1", "replacement": "user_id=2"}]
TYPICAL IDOR WORKFLOW:
search_traffic(query="/api/users/") → get flow_id
extract_session_variable(flow_id, regex="Bearer ([\w.-]+)", name="jwt")
replay_flow(flow_id, replacements=[{"regex": "/users/1", "replacement": "/users/2"}])
Args: flow_id: The captured flow to replay replacements: List of {"regex": "pattern", "replacement": "value"} objects for partial modification follow_redirects: Follow HTTP 3xx redirects (default true). Set false to inspect redirect targets.
Inputs: flow_id (required), replacements, follow_redirects. Returns: result
search_trafficA
Search captured traffic by keyword, domain, HTTP method, or status code.
PREREQUISITE: Proxy must be running and have captured traffic.
Use this instead of get_traffic_summary when you need to find specific requests. All filters are optional and can be combined (AND logic).
Examples:
search_traffic(query="password") — find flows containing "password" in URL or body
search_traffic(domain="api.target.com", method="POST") — find all POSTs to the API
search_traffic(status_code=401) — find unauthorized responses
Args: query: Keyword to search in URL, request body, and response body domain: Filter by exact domain (e.g. "api.target.com") method: Filter by HTTP method: "GET", "POST", "PUT", "DELETE", etc. status_code: Filter by exact response status code (e.g. 200, 401, 500) limit: Maximum results to return (default 50)
Inputs: limit, query, domain, method, +1 more. Returns: result
send_raw_requestA
Send a hand-crafted raw HTTP request (like Burp Repeater's raw editor). No proxy required.
REQUIRES: approved=true (human must approve sending potentially destructive requests).
Use this when you need full control over request formatting — multipart uploads, unusual headers, HTTP smuggling payloads, etc. For replaying captured traffic, use replay_flow instead.
Example raw request: POST /api/login HTTP/1.1 Host: target.com Content-Type: application/json
{"username":"admin","password":"test"}SECURITY: SSRF protection blocks requests to localhost/private IPs.
Args: raw: Complete raw HTTP request text (request line + headers + blank line + body) host: Override the Host header for routing (optional — extracted from Host header if omitted) port: Target port (default: 443 for HTTPS, 80 for HTTP) tls: Use HTTPS (default true). Set false for plain HTTP targets. follow_redirects: Follow HTTP 3xx redirects (default true) approved: MUST be true. Set this ONLY after the human user has explicitly approved this action.
Inputs: raw (required), tls, host, port, +2 more. Returns: result
set_scopeA
Limit which domains the proxy records. Call AFTER manage_proxy(action="start").
By default, ALL traffic is recorded. Use this to focus on specific target domains and reduce noise. Static assets (.jpg, .css, .woff, etc.) and OPTIONS requests are always ignored regardless of scope.
Examples:
set_scope(allowed_domains=["target.com", "api.target.com"]) — only record these domains
set_scope(allowed_domains=[]) — reset to record everything
Args: allowed_domains: List of domains to record. Subdomains must be listed explicitly. Empty list = record all traffic.
Inputs: allowed_domains (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 39 tools
The tool set covers a wide range of proxy, browser, and traffic functions, but there is notable overlap between proxy-level and browser-level interception tools (e.g., add_interception_rule vs browser_intercept_request) and between extract_from_flow and extract_session_variable. Descriptions clarify the differences, but the 39-tool surface makes misselection possible.
Naming is inconsistent across the set: browser_* tools use a domain-prefix convention, while proxy tools mix verb_noun (manage_proxy, search_traffic) and noun_verb (proxy_status, extract_session_variable). No uniform verb_noun pattern is applied across all tools.
At 39 tools, the surface is heavy and exceeds the typical range. The broad scope of proxy, browser, and pentesting functionality somewhat justifies the size, but it still feels bloated compared to more focused servers.
The tool set covers the full lifecycle of proxy management, traffic capture/inspection/replay, browser automation, and advanced testing features like fuzzing and scripting. Minor gaps exist (e.g., no direct flow deletion, no tab management beyond listing), but agents can complete workflows using the available tools.
Maintenance
Related MCP Connectors
Cloud browsers for AI agents: get past bot detection, sign in with MFA, run web tasks at scale.
Cloud browsers for AI agents: saved logins, residential IPs, live human takeover, 57 browser tools.
WAF-bypass web scraper and passive URL mapper for AI agents with zero pay-on-fail.
Browser agents and stealth cloud browsers for AI: run web tasks, fill forms, extract data.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables LLM-powered browser automation and security testing with features like browser management, network monitoring, DOM manipulation, and captcha handling.521-
- AlicenseNot gradedqualityCmaintenanceEnables autonomous AI agents and penetration testers to conduct authorized security audits with persistent cross-session memory, zero-trust secret scrubbing, dynamic OWASP/ASVS checklists, and hallucination-free exploit PoC generation from captured traffic.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to control a local Chromium browser via CDP for page snapshots, screenshots, human-like interactions, autonomous crawling, API/GraphQL reconnaissance, authenticated differential testing, and Burp-like intercept, repeater, and intruder workflows with scope enforcement and audit logging.MIT
- AlicenseBqualityBmaintenanceEnables AI agents to conduct authorized pentests and bug-bounty workflows with scope enforcement, audit logging, reconnaissance, safe vulnerability checks, payload/wordlist generation, and professional report generation.14MIT