scout-mcp-server
Provides tools for retrieving 2FA codes from Twilio SMS, enabling automated OTP entry during browser automation.
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., "@scout-mcp-server Scout the homepage of github.com"
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.
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:
Scout — compact structural overview (~200 tokens, not a raw DOM dump)
Find — search for elements by text, type, or selector
Act — click, type, select, navigate
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.
Related MCP server: Scout
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.
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:
Open
chrome://extensions, enable Developer mode, click "Load unpacked", select theextension/directory from the Scout repoClick the Scout MCP Bridge toolbar icon and toggle it Active
Call
launch_session(connection_mode="extension")from your AI client
Scenario | Recommended Mode |
Sites where you're already logged in |
|
Anti-detection scraping or CI/CD |
|
Sites requiring 2FA/SSO you've already passed |
|
Parallel sessions or headless automation |
|
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
Scout | Playwright MCP | Chrome Extension MCP | Selenium / scripts | |
Works on sites you don't control | Yes | Limited — your own app | Limited — your active session | Blocked by detection |
Context footprint | Compact scout (~200 tokens per call) | Full screenshot (~124k tokens per call) | You provide selectors | You provide selectors |
Credential safety | Never in conversation | Plaintext in context | Plaintext in context | In your script |
Anti-detection | Built-in | None | None | None |
2FA | Built-in | No | No | You build it |
Export to script | One command | No | No | You write it |
Cross-platform scheduling | One command | No | No | You configure it |
Benchmarks
Task | Scout context | Playwright MCP context | Reduction | Wall-clock | Success |
Fact lookup (Wikipedia) | ~1,264 tokens | ~124,000 tokens | 98% fewer | 15.8s | 3/3 |
Form fill + verify (httpbin) | ~3,799 tokens | ~124,000 tokens | 97% fewer | 52.5s | 3/3 |
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-serverOr run without installing:
uvx scout-mcp-serverVia npm
npx -y @stemado/scout-mcpConfigure 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-mcpRestart 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
cwdfield sets the working directory for the Scout server. Without it, Claude Desktop may launch Scout from a system directory (e.g.C:\Windows\System32on 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:
Explicit
env_filepath passed tofill_secretSCOUT_ENV_FILEenvironment variable.envin the current working directory
Variable | Description |
| Set to |
| Twilio account SID for 2FA code retrieval |
| Twilio auth token |
| Twilio phone number receiving 2FA SMS codes |
| Override the default Chrome extension ID for Native Messaging auth (only needed for custom extension builds) |
| Override NM host manifest directory for non-Chrome browsers (Brave, Chromium, Edge) |
Security
Credential isolation —
fill_secretreads from.envserver-side; passwords never enter the conversationHeader redaction — Authorization, Cookie, and API key headers scrubbed from network logs
Export scrubbing — credentials parameterized as environment variable references
URL scheme allowlist — only
httpandhttpsschemes permitted; all others rejectedSSRF protection — IP addresses normalized via
ipaddressmodule to catch IPv6-mapped IPv4 bypasses; blocks cloud metadata endpoints (AWS, GCP, Alibaba), loopback, and link-local addressesSafe XML parsing — uses
defusedxmlto prevent XXE attacks when processing SpreadsheetML filesJS execution timeout — 2-minute cap on
execute_javascriptwith graceful error responseScheduler 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
Tool | Description |
| Open a browser (headed or headless, optional proxy) or connect to an existing Chrome via extension mode |
| Check Chrome extension connection status |
| Structural page overview: iframes, shadow DOM, element counts |
| Search for elements by text, type, or CSS selector |
| Click, type, select, navigate, scroll, hover, wait |
| Type credentials from |
| Retrieve a 2FA OTP code from Twilio SMS |
| Run arbitrary JS in the page context |
| Capture the page as PNG or JPEG |
| Deep-inspect visibility, overlays, shadow DOM, ARIA |
| Convert and move downloaded files |
| Export the full session as a structured workflow log |
| Watch HTTP traffic to discover API endpoints under the UI |
| Record the browser session as MP4 |
| Close the browser and release resources |
| Create an OS-level scheduled task |
| List scheduled tasks |
| Remove a scheduled task |
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 templateSchedule 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-serverLicense
MIT
Available Tools
21 toolsbrowseA
Fetch a web page and extract its content as clean markdown.
Lightweight alternative to the full Scout session flow. One tool call, content out. Uses HTTP by default with automatic stealth browser fallback for bot-protected pages.
Args: url: The page URL to fetch. query: Optional — extract only content relevant to this query. max_length: Optional — cap response length in characters. 0 = unlimited.
Inputs: url (required), query, max_length. Returns: result
check_extensionA
Check the status of the Scout Chrome extension connection.
Returns the extension connection status: whether the relay server is running, whether the extension is connected, and installation instructions if needed.
Inputs: no named parameters.
close_sessionA
Close the browser session and release all resources.
Always call this when automation exploration is complete.
Args: session_id: Session ID to close.
Inputs: session_id (required).
execute_action_toolA
Perform a single interaction in the live browser session.
Supports clicking, typing, selecting, navigating, scrolling, and waiting. Always scout after executing an action to observe the result.
Args: session_id: Active session ID. action: The action to perform. selector: CSS selector of the target element. Required for click, type, select, hover, clear, upload_file. value: Text to type, option to select, URL to navigate to, key to press, wait duration, or file path to upload. frame_context: Iframe selector path for the target element. Use 'main' or omit for top-level. wait_after: Milliseconds to wait after action completes. Default: 500.
Inputs: session_id (required), action (required), selector, value, +2 more.
execute_javascriptA
Execute arbitrary JavaScript in the page context and return the result.
Use this to debug click failures, read shadow DOM content, dispatch custom events, extract data, or perform any DOM operation not covered by other tools.
Args: session_id: Active session ID. script: JavaScript code to execute. The last expression is returned as the result. Scripts with explicit 'return' statements also work for backward compatibility. frame_context: Iframe selector path for execution context. Use 'main' or omit for top-level.
Inputs: session_id (required), script (required), frame_context.
fill_secretA
Type a secret value from .env into a form field without exposing it in the conversation.
The server reads the value from the .env file and types it directly into the target element. The actual value never appears in tool parameters or responses.
Args: session_id: Active session ID. env_var: Name of the environment variable in .env (e.g., 'APP_PASSWORD'). selector: CSS selector of the target input field. frame_context: Iframe selector path for the target element. Use 'main' or omit for top-level. clear_first: Clear the field before typing. Default: true. wait_after: Milliseconds to wait after typing. Default: 500.
Inputs: session_id (required), env_var (required), selector (required), frame_context, +2 more.
find_elementsA
Search for specific interactive elements on the current page.
Returns matching elements with selectors, text, and attributes. Call scout_page_tool first to cache the page structure, then use this tool to find specific elements by text, type, or CSS selector.
Args: session_id: Active session ID. query: Text or selector to search for (case-insensitive substring match). Matches against element text, selector, id, name, aria-label, placeholder, href. element_types: Filter by tag name, e.g. ['button', 'input', 'a']. visible_only: Only return visible elements. Default: true. frame_context: Limit search to a specific iframe (use selector from scout report). max_results: Maximum elements to return. Default: 25.
Inputs: session_id (required), query, element_types, visible_only, +2 more.
get_2fa_codeA
Fetch a 2FA OTP code from Twilio SMS — call this AFTER clicking 'Send Code'.
Polls the Twilio Messages API until a new SMS matching app_keyword arrives, then extracts and returns the OTP code. Twilio credentials are read from .env and never exposed in tool responses.
Call this tool AFTER triggering the 2FA send in the browser. The baseline inbox state is captured at call time; Twilio delivery latency (2-10s) gives sufficient buffer before the first poll.
Args: app_keyword: Case-insensitive keyword to match in the SMS body. Use the site name, e.g. 'paycom', 'chase', 'google'. code_pattern: Regex to extract the OTP. Default: 6-digit number. Override for 8-digit or alphanumeric codes. timeout: Seconds to wait for the code before giving up. Default: 60.
Required .env entries: TWILIO_ACCOUNT_SID — Twilio Account SID TWILIO_AUTH_TOKEN — Twilio Auth Token TWILIO_PHONE_NUMBER — Digits-only recipient number (e.g. 14155551234)
Inputs: app_keyword (required), code_pattern, timeout. Returns: result
get_security_logA
Return recent security events from the Scout security log.
Useful for auditing a session before exporting a workflow — if a session had injection attempts, that should inform whether the workflow is trustworthy.
Args: session_id: Filter to events from this session only. severity: Filter by severity level: 'info', 'warning', or 'critical'. limit: Maximum number of events to return. Default: 50.
Inputs: session_id, severity, limit.
get_session_historyA
Return the complete structured history of a browser session.
Includes every action taken, every scout report (summarized), every network event captured, and the sequence of URLs visited. Use this data to compose botasaurus-driver scripts.
Args: session_id: Session ID (active or recently closed).
Inputs: session_id (required).
inspect_element_toolA
Inspect a single DOM element in detail — visibility, position, shadow DOM, overlays, and more.
Use this to diagnose why a click didn't work, check if an element is obscured by an overlay, verify shadow DOM context, or examine element state before interacting.
Args: session_id: Active session ID. selector: CSS selector of the element to inspect. frame_context: Iframe selector path. Use 'main' or omit for top-level. include_listeners: Detect inline event handlers (onclick, etc.). Default: false. include_children: Include child element summary. Default: true.
Inputs: session_id (required), selector (required), frame_context, include_listeners, +1 more.
launch_sessionA
Launch a new browser session via Botasaurus with anti-detection enabled.
The browser stays alive across all subsequent tool calls until close_session is called. Optionally navigate to an initial URL.
Args:
url: Initial URL to navigate to after launch. If omitted, opens a blank page.
headless: Run browser in headless mode. Default: false (headed, for observation).
profile: Optional Chrome profile for session persistence.
A bare name (e.g., 'work-portal') creates a Scout-managed profile
at /.scout/profiles// that persists cookies, localStorage,
and all browser state across sessions.
An absolute path (e.g., 'C:\Users...\User Data') uses an
existing Chrome profile directory directly.
If omitted, a temporary profile is used and deleted on close.
proxy: Optional proxy URL (e.g., 'http://user:pass@host:port').
WARNING: Using a proxy triggers botasaurus-driver's proxy authentication
subsystem, which imports javascript-fixes — a package that runs
'npm install' at import time without a lockfile. Only use proxy in
trusted environments where Node.js is installed.
download_dir: Directory for downloaded files. Default: '/.scout/downloads'.
Relative paths are resolved from the server's working directory.
connection_mode: How to connect to Chrome. 'launch' (default) starts a new
browser instance. 'extension' connects to your existing
Chrome via the Scout extension, preserving logged-in sessions.
allowed_domains: Optional list of domains allowed for fill_secret credential
typing and cross-origin navigation (extension mode).
Example: ['example.com', 'login.example.com'].
If omitted, fill_secret works on any domain (with a warning).
allow_localhost_port: Optional port number (1-65535) to allow localhost/loopback
navigation on. Example: 3000 permits http://localhost:3000 only.
If omitted, localhost is blocked. The SCOUT_ALLOW_LOCALHOST env var
overrides this to allow all ports.
Inputs: url, headless, profile, proxy, +4 more.
monitor_networkA
Control network monitoring for the current session.
Start monitoring before performing actions that trigger API calls or downloads, then query to see what was captured.
Args: session_id: Active session ID. command: start: begin capturing. stop: stop. query: return captured events. wait_for_download: block until download. url_pattern: Optional regex pattern to filter captured requests by URL. timeout_ms: For wait_for_download: maximum wait time. Default: 30000. capture_response_body: Whether to capture response bodies (adds overhead). Default: false. limit: Maximum number of events to return in a query response. Default: 100. offset: Number of matching events to skip before returning results. Default: 0.
Inputs: session_id (required), command (required), url_pattern, timeout_ms, +3 more.
process_downloadA
Process a downloaded file: convert format, rename, and move to destination.
Call this after a download completes. Handles format conversion (e.g., SpreadsheetML 2003 XML to CSV), filename pattern application, and file delivery to a target directory.
Args: session_id: Active session ID. source_format: Source file format. Use "auto" to detect from file contents. Known formats: spreadsheetml_2003, xls_binary, xlsx, csv. target_format: Target format to convert to (e.g., "csv"). Default: "csv". target_filename: Filename pattern with tokens: {MM}, {dd}, {yyyy}, {HH}, {mm}, {suggested}. Example: "Complete Enrollments Report {MM}.{dd}.{yyyy}.csv" target_directory: Destination directory. UNC paths supported (e.g., \server\share\path). guid: Specific download GUID to process. If omitted, processes the most recent completed download.
Inputs: session_id (required), source_format, target_format, target_filename, +2 more.
record_videoA
Control video recording for the current browser session.
Records the browser screen using CDP screencast and encodes to MP4 or GIF. Requires ffmpeg for video encoding: install imageio-ffmpeg (pip install 'imageio-ffmpeg') or have ffmpeg on your system PATH. Without it, raw JPEG frames are saved instead.
Args: session_id: Active session ID. command: start: begin recording. stop: stop and encode video. status: check recording state. max_width: Maximum video width in pixels. Default: 1920. max_height: Maximum video height in pixels. Default: 1080. quality: JPEG frame quality (1-100). Default: 95. target_fps: Target frames per second (approximate). Default: 15. output_format: Output encoding format when stopping. "mp4" (default) or "gif". GIF uses palette-optimized encoding at 10fps/800px width for README-embeddable demos.
Inputs: session_id (required), command (required), max_width, max_height, +3 more.
schedule_createA
Create or update a scheduled task for an exported SCOUT workflow.
Generates a platform-appropriate run script and registers the schedule with the OS task scheduler (Windows Task Scheduler, macOS launchd, or Linux cron).
Args: name: Workflow name. Must match .py inside workflow_dir. workflow_dir: Absolute path to the workflow directory (e.g., 'D:/Projects/app/workflows/enrollment'). schedule: Frequency — one of DAILY, WEEKLY, ONCE. time: Time to run in HH:MM 24-hour format (e.g., '06:45', '14:00'). days: Comma-separated day names for WEEKLY schedules (e.g., 'MON,WED,FRI'). Required when schedule is WEEKLY.
Inputs: name (required), workflow_dir (required), schedule (required), time (required), +1 more.
schedule_deleteA
Delete a scheduled task from the OS task scheduler.
Removes the task from Windows Task Scheduler, macOS launchd, or Linux cron. Does not delete the workflow files — only the schedule.
Args: name: Name of the scheduled task to delete.
Inputs: name (required).
schedule_listA
List all SCOUT scheduled tasks on this machine.
Returns all tasks registered with the OS task scheduler (Windows Task Scheduler, macOS launchd, or Linux cron) under the SCOUT namespace.
Inputs: no named parameters.
scout_page_toolA
Perform deep reconnaissance on the current page state.
Returns a structural overview of the page: metadata, iframe hierarchy, shadow DOM boundaries, and element counts. Use find_elements to search for specific interactive elements by text, type, or selector.
Args: session_id: Active session ID from launch_session. focus_frame: Optional iframe CSS selector to scout instead of the full page. detail_level: 'summary' (default) returns compact overview with element counts. 'full' returns all interactive elements (large response).
Inputs: session_id (required), focus_frame, detail_level.
take_screenshot_toolA
Capture a screenshot of the current page. The screenshot is always saved to disk.
By default, also returns the image inline so Claude can see it (~1,600 tokens at typical browser resolution). Set return_image=false when capturing screenshots as file artifacts that don't need visual analysis — the file_path in the JSON response is sufficient to reference or copy the file.
Args: session_id: Active session ID. format: Image format: 'png' or 'jpeg'. Default: 'png'. quality: JPEG quality (1-100). Only used when format='jpeg'. clip_x: Left coordinate of clip region (viewport pixels). clip_y: Top coordinate of clip region (viewport pixels). clip_width: Width of clip region. clip_height: Height of clip region. full_page: Capture the full scrollable page, not just viewport. Default: false. Note: pages with lazy-loaded content may still show incomplete results. return_image: Return image inline for visual inspection. Default: true. Set to false when collecting screenshots as file artifacts to save ~1,600 tokens per screenshot.
Inputs: session_id (required), format, quality, clip_x, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool has a clearly distinct purpose, from session management (launch/close) to interaction (click/type), page reconnaissance, network monitoring, downloads, video recording, scheduling, and security. No two tools overlap in function; even similar actions like browse and scout_page_tool operate in different contexts (standalone vs. session).
Most tools follow a verb_noun pattern (e.g., allow_navigation, check_extension, execute_javascript). However, a few deviate: the schedule tools use noun_verb (schedule_create), and some tools have a 'tool' suffix (execute_action_tool, inspect_element_tool) while others do not. This minor inconsistency prevents a perfect score but does not hinder readability.
With 21 tools, the server strikes an excellent balance between comprehensive capabilities and manageable scope. Each tool addresses a specific need in web automation, and the count feels well-calibrated for a tool server that handles sessions, interactions, media, scheduling, and security.
The tool surface covers the full lifecycle of web automation: session control, navigation, element interaction, JavaScript execution, page analysis, screenshots, video recording, network monitoring, download processing, 2FA, security auditing, and scheduling. There are no obvious gaps; agents can accomplish complex workflows without resorting to workarounds.
Maintenance
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Browser automation MCP for whole web tasks in a cloud browser: saved logins, bot checks, replays.
Web scraping MCP server — scrape, extract structured data, screenshot any site with anti-bot bypass.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables AI assistants to control a real web browser with stealth capabilities, avoiding bot detection while performing tasks like clicking, filling forms, taking screenshots, and extracting data.1156 npm26MIT
- AlicenseBqualityDmaintenanceBrowser MCP server that connects to your existing browser, preserving sessions, passwords, and extensions, enabling AI agents to interact with web pages without bot detection.313 npm1MIT
- AlicenseAqualityDmaintenanceAn AI-native stealth browser MCP server that uses AI vision navigation and bot detection bypass, enabling natural language browser automation.17MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for controlling a local camofox-browser instance, enabling LLM agents to perform web automation tasks such as navigation, interaction, snapshotting, and content extraction.42 npmMIT