Shade Browser Security MCP
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., "@Shade Browser Security MCP Open a fresh isolated profile and navigate to example.com, then dump the DOM."
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.
Shade Browser Security MCP
This repository exposes only the explicitly classified SECURITY tools from
Shade Browser through a standalone MCP server. The implementation reuses the
shared shade_browser_mcp browser core vendored in this repository; the
public shade-browser-security entry point registers a separate FastMCP
instance with the SECURITY allow-list only.
Run locally:
pip install -e '.[dev]'
shade-browser-securityThe reduced/general server is maintained separately in the
shade-browser-mcp repository's reduced-safe branch.
MCP server for Brave CDP browser automation across 20 flock-protected profile slots. Built on FastMCP + Playwright Python.
What this is
A one-shot-installable Model Context Protocol server that gives Claude Code a Brave browser with real cookies, auto-launched on demand, across 20 isolated slots (ports 61000-61019). Each slot gets its own profile copy by default, so parallel agents never collide on tabs or sessions. Persistent mode reuses a stable per-slot profile for manual logins, extensions, and browser config.
Related MCP server: mcp-browser-automation
Install (3 commands)
uv tool install git+https://github.com/Atlas-X-AI/shade-browser-mcp
shade-browser-mcp postinstall
claude mcp add shade-browser-mcp --scope user -- shade-browser-mcpThen restart Claude Code. Tools appear as mcp__browser-automation__*.
What each step does
Step | What it does |
| Installs the Python package globally (isolated venv managed by uv) |
| Runs |
| Registers the MCP in |
Upgrade an existing user-scope MCP install
Claude Code user-scope MCP registration runs the uv tool install copy of
shade-browser-mcp. New tools do not appear in already-installed Hayden agent
sessions until that tool install is replaced and Claude Code reconnects to the
server.
For local development on the checked-out branch:
git switch feat/form-filler-bolt-on
uv tool install --force --editable .Or install this branch directly from Git:
uv tool install --force git+https://github.com/Atlas-X-AI/shade-browser-mcp@feat/form-filler-bolt-onThen fully exit and relaunch each Claude Code session that should see the new schema. Existing sessions keep the old MCP process and old tool list until they restart or reconnect that MCP server.
Smoke-test the installed server's tool registry:
uvx --from fastmcp fastmcp list --command "shade-browser-mcp" --json \
| grep -E '"name": "form_(scan|fill|gate_check)"'Prerequisites
Python 3.10+
uv —
curl -LsSf https://astral.sh/uv/install.sh | shClaude Code CLI (for
claude mcp add)Brave browser at
/opt/brave-bin/braveor/usr/bin/brave-browserBrave profile at
~/.config/BraveSoftware/Brave-Browser(that's where your cookies come from — each slot gets a freshcp -acopy)
Run shade-browser-mcp doctor after install to verify all six prerequisites.
Commands
shade-browser-mcp # runs FastMCP stdio server (default — what Claude Code invokes)
shade-browser-mcp serve # same as above
shade-browser-mcp postinstall # playwright install chromium
shade-browser-mcp doctor # health check: Brave, profile, Playwright, Claude registration
shade-browser-mcp --versionRuntime identity and safe rolling reload
Call the machine-readable MCP tool below on every connected server and after connecting to a candidate build:
browser_runtime_status(
client_id="launcher-a",
expected_version="0.1.10",
expected_revision="<candidate-revision>"
)The response includes the running server's version, revision, pid,
UTC started_at, transport, effective focus defaults, and top-level
reload_required/should_reload booleans. A build mismatch is deterministic:
status is reload_required, reload.action is reconnect, and
reload.process_action is always none. The server does not kill or restart
itself and does not raise Brave, move the pointer, type, or call
bring_to_front for this protocol. Focus defaults are
browser_navigate=false and browser_switch_tab=false.
For a rolling reconnect, the launcher/client owns the transport lifecycle:
Start the candidate server alongside the current server, injecting an immutable build value such as
SHADE_BUILD_REVISION=$(git rev-parse --short HEAD).Probe the candidate with
browser_runtime_statuswithout expected values and record its returned version/revision as the target identity.Ask one client at a time to report status against that target identity. A client on the old server receives
reload_required=true; close only that client's transport and reconnect it to the candidate. Other clients remain usable on the old server until their own turn.Verify each reconnected client with the same expected version/revision. A matching response has
status=ready,reload_required=false, and the new PID/start time. Only the launcher decides when the old server is retired; this tool never performs that action.
If expected_version/expected_revision is omitted, the tool reports the
identity but cannot detect staleness. If the revision is unknown, configure
SHADE_BUILD_REVISION in the launcher; do not infer freshness from PID or
start time. A reconnect failure leaves the existing client transport alone and
must be handled by the launcher/client's normal retry policy.
Form-Filler Tools
Three bolt-on tools scan and fill ordinary web forms from a runtime JSON profile path:
form_scan(slot=-1)
form_fill(slot=-1, profile="docs/examples/form-fill-demo-profile.json", allow_submit=false)
form_gate_check(slot=-1, profile="docs/examples/form-fill-demo-profile.json")form_scan returns field IDs, labels, required signals, option lists, upload
controls, submit/advance controls, and profile-key hints such as
person.email. form_fill reads the profile at call time, fills grounded
fields, verifies read-back, and returns counts plus a gate check. Its response
also includes additive field_outcomes entries with tier_used, committed,
readback_value, escalate, and reason for each resolved field. Outcomes may
also include attribution, for example pre_filled_verified:radio, when an
already-filled control was verified before any actuation. form_gate_check
verifies required fields, identity read-back, required uploads, visible page
errors, and detector health.
Profile shape:
{
"person": {"email": "casey@example.test", "first_name": "Casey"},
"company": {"name": "Example Labs"},
"files": {"Resume": "relative/or/absolute/path.txt"},
"values": {"Work Type": "full time", "Location": ["Remote United States", "Remote"]},
"never_submit": true
}values entries override inferred person/company mappings by field ID or
label. Option choices are grounded only by exact text/value equality after
mechanical normalization, or by explicit profile variant lists. Relative upload
paths resolve relative to the profile file. If never_submit is true,
form_fill(..., allow_submit=true) still refuses to click submit.
Worked examples after navigating a browser slot to a form:
form_scan(slot=4)Returns form inventory such as field IDs, labels, required signals, upload controls, options, submit controls, and inferred profile-key hints.
form_fill(slot=4, profile="docs/examples/form-fill-demo-profile.json", allow_submit=false)Fills grounded fields from the JSON profile, verifies read-back, uploads files
declared in files, and returns a nested gate check without submitting.
form_gate_check(slot=4, profile="docs/examples/form-fill-demo-profile.json")Reports whether required fields, identity fields, required uploads, visible validation errors, and detector health are all ready for a guarded submit.
See docs/examples/form-fill-demo-profile.json and
docs/examples/form-fill-live-slot-transcript.md for a real-slot loopback
fixture transcript. docs/examples/form-fill-local-transcript.md is a shorter
local fixture summary. The consolidated capabilities, schema, safety, packaging,
and opt-in upgrade guide is docs/form-fill/README.md.
Headed vs headless mode
By default, shade-browser-mcp launches Brave headed if DISPLAY or WAYLAND_DISPLAY is set, and headless otherwise (CI, SSH sessions without X forwarding, systemd units without a user display).
To force a visible window regardless of env:
export HEADED=1
shade-browser-mcpTo force headless on a desktop session:
unset DISPLAY WAYLAND_DISPLAY
shade-browser-mcpThe HEADED=1 knob is useful when you want to watch an AI agent drive the browser, or when the MCP daemon was launched from an env that lacks DISPLAY but you later want to attach visibly.
Persistent profiles and Bitwarden
Default slot mode refreshes ~/.cache/brave-cdp/slot-N/ from the real Brave profile on launch. Persistent mode uses ~/.cache/brave-cdp/persistent/slot-N/ and reuses that profile across launches, so manual ChatGPT login, installed extensions, and browser settings survive.
export SHADE_PROFILE_MODE=persistent
export SHADE_INGEST_BW=1
shade-browser-mcpYou can also launch one slot manually:
launch-brave-cdp 5 --persistentSHADE_INGEST_BW=1 runs ~/bin/bw-ensure.sh when BW_SESSION is absent and passes the resulting BW_SESSION only through the MCP/Brave launcher environment. Tokens are not written to manifests, screenshots, or browser session files.
Architecture (one-liner)
BrowserManager._ensure_brave_alive() on each tool call → httpx-probe port → if dead, subprocess.run(bash launch-brave-cdp N) with env including DISPLAY/WAYLAND_DISPLAY/XAUTHORITY/XDG_RUNTIME_DIR → poll 20s at 1Hz → playwright.connect_over_cdp(). Slots are flock-protected via cdp_slots.claim_slot().
Per-slot CDP auth proxy (Phase 1, library only)
A protocol-layer slot-ownership proxy ships in shade_browser_mcp.cdp_proxy. Each slot now carries an auth_token (256-bit, generated by claim_slot) and a private_port (62000+slot) where Brave will eventually bind. The proxy listens on the public port (61000+slot), validates Authorization via a /t/<token>/... URL prefix, and rewrites webSocketDebuggerUrl so Playwright's WS upgrade also carries the token.
CLI:
python -m shade_browser_mcp.cdp_proxy <slot> # passthrough mode
python -m shade_browser_mcp.cdp_proxy <slot> --require-token # enforcePhase 1 ships the library + tests + audit fixes only — the proxy is not yet wired into _ensure_brave_alive. That production wiring (and the matching launch-brave-cdp --private-port flag) lands in a Phase 2 follow-up. Users who want to opt in early can drive the proxy module directly. See DONE.md for the migration ledger and audit-deferred items.
Shade Fleet Console (local dashboard)
A read-mostly local web console for watching and steering the 20 slots. It is a single-host operator tool, not a shared service.
export SHADE_DASHBOARD_TOKEN=$(openssl rand -hex 32)
shade-browser-mcp dashboard --port 8790Loopback only. The console binds
127.0.0.1exclusively and refuses to start on any non-local host (no--allow-nonlocalescape hatch in v1).Token via env. The bearer token is read from the
SHADE_DASHBOARD_TOKENenvironment variable.Opener URL carries the token in the fragment, never a query string. On start the server prints
http://127.0.0.1:8790/#token=<token>. The fragment (#token=...) is never sent to the server in a request line and never lands in access logs; a query string (?token=...) would, so it is deliberately not used.API auth uses a header. Every
/api/*request must carryAuthorization: Bearer <token>. The page JS reads the token from the URL fragment and replays it as that header; it is never written tolocalStorage/sessionStorage.
Phase 2 endpoint model
Phase 2 splits each slot into a private upstream port and a public proxied port:
Port | Who binds it | Reachable by | Auth |
| Brave (CDP) | proxy only | n/a (loopback, private) |
| per-slot auth proxy | local clients | tokenized path |
Brave now binds the private per-slot port
127.0.0.1:6200N.The per-slot auth proxy listens on the public port
127.0.0.1:6100N.Internal Playwright attach uses the tokenized path
http://127.0.0.1:6100N/t/<token>— the token rides in the URL path so it survives the WebSocket upgrade.Direct unauthenticated access to
6100Nis rejected with401. A missing or wrong token never reaches Brave.
Synthetic Action View
The console renders each slot's recent activity from structured data, not from a live pixel feed:
Structured browser events are written to
browser-events.jsonl(a separate stream from the existingactions.jsonlaudit log), surfaced throughGET /api/slots/{n}/events.Each slot shows its current URL/title plus compact ARIA/text snapshots.
Screenshots are captured only on demand, on failure, or as evidence — there are no continuous thumbnails and no rolling viewport capture.
POST controls (all under Authorization: Bearer <token>):
POST /api/slots/{n}/navigate # navigate the slot to a URL
POST /api/slots/{n}/screenshot # capture one frame on demand / as evidence
POST /api/slots/{n}/release # release the slot
POST /api/slots/{n}/focus # focus / observe the slot
POST /api/slots/{n}/takeover # operator takeover
POST /api/slots/{n}/resume # hand control back to the agentExample read call (sanitized fleet view):
SHADE_TOKEN="$SHADE_DASHBOARD_TOKEN"
curl -H "Authorization: Bearer $SHADE_TOKEN" http://127.0.0.1:8790/api/fleetThe single-frame capture endpoint is POST /api/slots/{n}/screenshot; issue it
only when you actually need an on-demand frame.
v1 non-goals
The console deliberately does not include:
an agent-task launcher from the web view,
continuous screenshots or live viewport streaming,
an injected in-page recorder,
cloud sync, multi-user accounts, TLS, or any public (non-loopback) binding.
Uninstall
claude mcp remove shade-browser-mcp --scope user
uv tool uninstall shade-browser-mcp
rm -rf ~/.cache/brave-cdp/ # purge slot profile copiesDevelopment
git clone https://github.com/Atlas-X-AI/shade-browser-mcp
cd shade-browser-mcp
uv sync --dev
uv run shade-browser-mcp doctorDesign notes
Vendored dependencies —
cdp_slots.pyandlaunch-brave-cdpship inside the package (loaded viaimportlib.resources). No symlinks, no external~/bin/scripts, no assumptions about the host.Wheel loses exec bit — the shell script is invoked via
bash <path> <slot>regardless of its executable bit after install.No Brave auto-install — intentional. The package won't try to install Brave for you; run
shade-browser-mcp doctorto find out if you're missing it.User-scope MCP registration — the server runs under
uv tool install's isolated venv;claude mcp add --scope userpoints Claude at the installed entry-point, no manual JSON surgery.
Supersedes
/home/anombyte/Hermes/current-projects/atlas-shade/shade-mcp/browser-server.py(monorepo path)/home/anombyte/bin/browser-mcp-proxy.sh(wrapper script)/home/anombyte/bin/launch-brave-cdp(now vendored)
Previous wiring relied on an external ~/bin/launch-brave-cdp and a symlinked cdp_slots.py from claude-launcher. That's fragile across reinstalls — this package fixes it.
Available Tools
18 toolsbrowser_apply_personalityB
Apply or regenerate a stealth personality profile for a browser slot.
Inputs: slot, personality_name. Returns: result
browser_cdp_commandC
Execute a raw CDP command.
Inputs: method (required), slot, params. Returns: result
browser_inject_passkeyC
Inject a Bitwarden passkey into an isolated slot and keep it alive.
Inputs: slot (required), bw_item_id (required). Returns: result
browser_inject_signerB
Inject a minimal EIP-1193 wallet provider. No MetaMask needed.
Inputs: private_key (required), slot, chain_id. Returns: result
browser_leak_checkA
Check for IP, DNS, and WebRTC leaks. Run after every tunnel assignment.
Inputs: slot. Returns: result
browser_network_interceptA
Capture network requests with full request/response bodies.
Inputs: slot, url_pattern, capture_body. Returns: result
browser_network_requestsA
Get recent network requests (useful for debugging API calls).
Inputs: slot, url_pattern. Returns: result
browser_os_input_clickC
Click via OS input on a private per-slot X display only.
Inputs: x (required), y (required), slot, display. Returns: result
browser_passive_reconC
Run passive reconnaissance against a domain.
Inputs: domain (required), slot. Returns: result
browser_rotate_ipB
Rotate to a new tunnel exit IP. Optionally preserves session state.
Inputs: slot, preserve_session. Returns: result
browser_solve_challengeA
Solve a detected Cloudflare Turnstile challenge via an external solver (premium).
Inputs: url, slot, site_key. Returns: result
browser_use_residentialA
Launch a browser slot through a residential proxy in a chosen region (premium).
Inputs: geo, slot. Returns: result
browser_use_torA
Launch a browser slot through Tor for .onion browsing.
Inputs: slot. Returns: result
browser_use_tunnelB
Launch a browser slot through a Shade VPN tunnel.
Inputs: slot, tunnel_id. Returns: result
browser_web3_monitorA
Install window.ethereum monitoring. Logs all wallet RPC calls.
Inputs: slot. Returns: result
browser_webauthn_bypassA
Create a virtual WebAuthn authenticator via CDP. Bypasses most WebAuthn.
Inputs: slot, rp_id. Returns: result
browser_ws_monitorB
Install WebSocket monitoring. Logs all WS frames via prototype patching.
Inputs: slot. Returns: result
form_scanC
Scan the current page for fillable form fields and gate controls.
Inputs: slot, previous_scan_state. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools have clear distinct purposes, but there is overlap among the network monitoring tools (browser_network_requests vs browser_network_intercept vs browser_ws_monitor) and the three browser_use_* variants (tor, tunnel, residential) are similar except for the network path. Descriptions help but an agent may struggle to pick the exact right tool in ambiguous situations.
All tools are snake_case and most start with 'browser_', but the pattern after the prefix is inconsistent: some use verb_noun (use_tor, solve_challenge), some are noun phrases (network_requests, passive_recon), and one (form_scan) lacks the browser_ prefix. This mixed convention is still readable but not uniform.
18 tools is slightly above the ideal 3-15 range but still manageable for a comprehensive security toolset. Each tool addresses a distinct aspect of browser security and anti-detection, so the count feels justified rather than bloated.
The toolset focuses heavily on network routing, monitoring, and stealth features, but omits basic browser lifecycle operations like navigate, screenshot, or close slot. Without a direct way to navigate to a URL (except via raw CDP), the surface is incomplete for practical security testing workflows.
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Unified 15-tool SEO, SERP, clean Markdown & GEO (LLM citation Share-of-Voice) MCP server.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceSecurity-hardened MCP server that gives AI assistants full control over your real browser session, supporting 36 tools for navigation, data extraction, monitoring, and more.MIT
- AlicenseBqualityDmaintenanceAn MCP server for generic browser automation using Playwright. Enables MCP clients to navigate pages, inspect elements, execute JavaScript, capture screenshots, and monitor console logs and network traffic via a headless Chromium instance.7ISC
- AlicenseAqualityCmaintenanceAn MCP server that runs concurrent, session-isolated Playwright browser contexts, so many agents can each drive their own browser at the same time without colliding.2310 npm5MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides structured control of a Playwright browser for QA, scraping, diagnostics, and reproducible browser workflows.MIT