scout-mcp-server

MCP server for browser automation with anti-detection. Scout pages, find elements, interact with websites, and monitor network traffic — from any AI client that supports the Model Context Protocol.

Built on botasaurus-driver for automatic fingerprint evasion and stealth browsing. Sites that block Playwright and Selenium see a normal browser session.

How It Works

Scout reads the page structure, then acts — the same way you'd inspect a page in DevTools before clicking anything:

1. Scout — compact structural overview (~200 tokens, not a raw DOM dump)
2. Find — search for elements by text, type, or selector
3. Act — click, type, select, navigate
4. Scout again — see what changed

Most browser-automation tools for AI take full-page screenshots and have the model interpret pixels. A single Playwright MCP screenshot adds ~124,000 tokens to the conversation context — and the model still has to guess at selectors from what it sees. Scout reads the DOM directly and returns a compact report (~200 tokens) with exact CSS selectors. An entire multi-step task with Scout uses fewer tokens than a single Playwright page snapshot.

See It In Action

Real-world scenarios demonstrating Claude Code + Scout working together on live websites — checking docs, researching errors, filling forms, downloading files, and more.

Scenario Catalog →

Credential Safety

fill_secret reads credentials from .env server-side and types them directly into form fields. The AI client only sees "chars_typed": 22 — never the actual value. Exported scripts use ${ENV_VAR} references. Authorization and Cookie headers are scrubbed from network logs before they reach the conversation.

2FA Support

get_2fa_code polls Twilio's SMS API for OTP codes — the AI clicks "Send Code" in the browser, the tool watches for the SMS, extracts the code, and types it in. Requires a Twilio account with an SMS number set as the 2FA recipient.

Anti-Detection

Scout uses Botasaurus under the hood, which handles browser fingerprinting and detection evasion automatically. Sites that block Selenium and Playwright see a normal browser session.

Chrome Extension Mode

By default, Scout launches its own browser. Extension mode connects to your existing Chrome instead — preserving your logged-in sessions, cookies, and browser state.

launch_session(connection_mode="extension")

Quick setup:

1. Open chrome://extensions, enable Developer mode, click "Load unpacked", select the extension/ directory from the Scout repo
2. Click the Scout MCP Bridge toolbar icon and toggle it Active
3. Call launch_session(connection_mode="extension") from your AI client

Extension mode sets no automation flags — your browser fingerprint stays identical to normal browsing. All 17 Scout tools work the same in both modes.

Full setup guide and troubleshooting: docs/chrome-extension.md

Comparison

Benchmarks

^{Claude Opus 4.6, 3 runs each. Full results: v0.4 | v0.2 (Sonnet)}

What these numbers measure: Both columns show context window footprint — how many tokens the task adds to your conversation. Playwright MCP returns a full-page accessibility snapshot in a single tool call (~124k tokens). Scout spreads the work across multiple small calls (~200 tokens each), so an entire multi-step task consumes less context than one Playwright snapshot. Less context means more room for follow-up work in the same conversation and lower per-turn API costs, since every subsequent API call re-sends the full conversation.

Wall-clock measures browser time only (session_duration_seconds from close_session). This excludes model reasoning between tool calls — add ~1–3 seconds per tool call for realistic end-to-end latency.

Install

Prerequisites: Python 3.11+, Google Chrome

Via PyPI (recommended)

pip install scout-mcp-server

Or run without installing:

uvx scout-mcp-server

Via npm

npx -y @stemado/scout-mcp

Configure Your AI Client

You configure Scout once. After that, your AI client starts and stops the server automatically — you never run it manually.

Claude Code

claude mcp add scout -- npx -y @stemado/scout-mcp

Restart Claude Code. Scout's 17 tools are now available in every session.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "scout": {
      "command": "npx",
      "args": ["-y", "@stemado/scout-mcp"],
      "cwd": "C:\\Users\\YourUsername"
    }
  }
}

Important: The cwd field sets the working directory for the Scout server. Without it, Claude Desktop may launch Scout from a system directory (e.g. C:\Windows\System32 on Windows), causing downloads and file operations to fail with permission errors. Set it to your home directory or any folder where Scout should have write access.

Cursor

In Cursor Settings > MCP Servers, add:

{
  "mcpServers": {
    "scout": {
      "command": "npx",
      "args": ["-y", "@stemado/scout-mcp"]
    }
  }
}

Windsurf / Continue / Other MCP Clients

Use the same JSON configuration above — it works with any MCP-compatible client.

Environment Variables

Scout loads variables from a .env file using this search order:

1. Explicit env_file path passed to fill_secret
2. SCOUT_ENV_FILE environment variable
3. .env in the current working directory

Security

• Credential isolation — fill_secret reads from .env server-side; passwords never enter the conversation
• Header redaction — Authorization, Cookie, and API key headers scrubbed from network logs
• Export scrubbing — credentials parameterized as environment variable references
• URL scheme allowlist — only http and https schemes permitted; all others rejected
• SSRF protection — IP addresses normalized via ipaddress module to catch IPv6-mapped IPv4 bypasses; blocks cloud metadata endpoints (AWS, GCP, Alibaba), loopback, and link-local addresses
• Safe XML parsing — uses defusedxml to prevent XXE attacks when processing SpreadsheetML files
• JS execution timeout — 2-minute cap on execute_javascript with graceful error response
• Scheduler name validation — regex pattern prevents path traversal in task scheduler namespaces
• Path traversal protection — validates all file paths
• Invisible character stripping — removes zero-width Unicode that could hide prompt injection
• Content boundary markers — wraps web-sourced data to distinguish data from instructions

Localhost navigation is blocked by default. Set SCOUT_ALLOW_LOCALHOST=1 to enable it for local development.

Tools

Workflow Export

Walk through a workflow conversationally, then export it as a standalone Python script:

workflows/<name>/
├── <name>.py              # Standalone replay script
├── <name>.json            # Portable workflow definition
├── requirements.txt
└── .env.example           # Credential template

Schedule exported workflows with the schedule_create tool — works on Windows (Task Scheduler), macOS (launchd), and Linux (cron).

Development

# Clone and install
git clone https://github.com/stemado/scout-mcp.git
cd scout
uv sync

# Run tests (no browser needed)
uv run pytest tests/ -m "not integration" -v

# Run integration tests (needs Chrome)
uv run pytest tests/ -v

# Run the MCP server locally
uv run scout-mcp-server

License

MIT