MCP Browser Actor

A powerful Model Context Protocol (MCP) server that provides advanced web scraping and browser automation capabilities using Scrapling on the Apify platform.

🚀 Features

• Multiple Fetcher Types: Choose between Simple HTTP, Dynamic (browser-based), and Stealthy (anti-detection) fetchers
• Cloudflare Challenge Solver: Automatically bypass Cloudflare protection
• Advanced Stealth Options: Block WebRTC, hide canvas fingerprinting, use real Chrome, and more
• Comprehensive Browser Automation: Full suite of browser interaction tools
• Element Finding & Extraction: CSS, XPath, text, regex, and tag-based selectors
• Session Management: Maintain browser context across multiple requests
• Pay-Per-Event Billing: Usage-based pricing for all tool calls
• Standby Mode: Ready instantly for incoming requests

🔧 Available Tools

Basic Fetching & Extraction

fetch_url

Fetch a webpage using different fetcher types.

Parameters:

• url (string): The URL to fetch
• fetcher_type (string): Type of fetcher - "simple", "dynamic", or "stealthy" (default: "stealthy")
• session_id (string): Session ID for maintaining browser context
• solve_cloudflare (boolean): Automatically solve Cloudflare challenges (default: false, stealthy fetcher only)
• block_webrtc (boolean): Block WebRTC to prevent IP leaks (default: false, stealthy fetcher only)
• real_chrome (boolean): Use real Chrome instead of Chromium (default: false, stealthy fetcher only)
• hide_canvas (boolean): Hide canvas fingerprinting (default: false, stealthy fetcher only)
• google_search (boolean): Simulate coming from Google search (default: false, stealthy fetcher only)
• proxy (string): Proxy URL (format: http://host:port or https://user:pass@host:port)

Example (Basic):

{
  "url": "https://example.com",
  "fetcher_type": "stealthy",
  "session_id": "my-session-1"
}

Example (With Cloudflare solving):

{
  "url": "https://protected-site.com",
  "fetcher_type": "stealthy",
  "solve_cloudflare": true,
  "session_id": "my-session-1"
}

Example (Full stealth mode):

{
  "url": "https://protected-site.com",
  "fetcher_type": "stealthy",
  "solve_cloudflare": true,
  "block_webrtc": true,
  "real_chrome": true,
  "hide_canvas": true,
  "google_search": true,
  "session_id": "my-session-1"
}

find_elements

Find elements on the current page using various selector types.

Parameters:

• selector (string): The selector string
• selector_type (string): "css", "xpath", "text", "regex", or "tag" (default: "css")
• session_id (string): Session ID to get the current page context
• first_match (boolean): Return only the first match (default: false)

Example:

{
  "selector": "h1.title",
  "selector_type": "css",
  "session_id": "my-session-1",
  "first_match": false
}

extract_element_content

Extract specific content from an element.

Parameters:

• selector (string): The selector to find the element
• selector_type (string): Type of selector (default: "css")
• extract_type (string): "text", "html", "attribute", or "json" (default: "text")
• session_id (string): Session ID
• attribute_name (string, optional): Required for extract_type="attribute"

Example:

{
  "selector": "a.link",
  "extract_type": "attribute",
  "attribute_name": "href",
  "session_id": "my-session-1"
}

Browser Navigation

browser_navigate

Navigate to a URL in the browser.

Parameters:

• url (string): The URL to navigate to
• session_id (string): Session ID
• wait_until (string): "load", "domcontentloaded", or "networkidle" (default: "load")
• solve_cloudflare (boolean): Automatically solve Cloudflare challenges (default: false)
• block_webrtc (boolean): Block WebRTC to prevent IP leaks (default: false)
• real_chrome (boolean): Use real Chrome instead of Chromium (default: false)
• hide_canvas (boolean): Hide canvas fingerprinting (default: false)
• google_search (boolean): Simulate coming from Google search (default: false)

Example (With Cloudflare solving):

{
  "url": "https://protected-site.com",
  "solve_cloudflare": true,
  "session_id": "my-session-1"
}

browser_go_back

Navigate back in browser history.

Parameters:

• session_id (string): Session ID

browser_go_forward

Navigate forward in browser history.

Parameters:

• session_id (string): Session ID

browser_reload

Reload the current page.

Parameters:

• session_id (string): Session ID
• wait_until (string): When to consider reload succeeded (default: "load")

Browser Interactions

browser_click

Click an element in the browser.

Parameters:

• selector (string): CSS selector of the element to click
• session_id (string): Session ID
• button (string): "left", "right", or "middle" (default: "left")
• click_count (integer): Number of clicks - 1 for single, 2 for double (default: 1)

Example:

{
  "selector": "button#submit",
  "session_id": "my-session-1",
  "button": "left",
  "click_count": 1
}

browser_type

Type text into an input element.

Parameters:

• selector (string): CSS selector of the input element
• text (string): Text to type
• session_id (string): Session ID
• delay (integer): Delay between key presses in milliseconds (default: 0)

Example:

{
  "selector": "input[name='username']",
  "text": "john.doe",
  "session_id": "my-session-1",
  "delay": 50
}

browser_select_option

Select an option from a dropdown.

Parameters:

• selector (string): CSS selector of the select element
• value (string, optional): Option value to select
• label (string, optional): Option label to select
• session_id (string): Session ID

Note: Either value or label must be provided.

browser_file_upload

Upload a file to a file input element.

Parameters:

• selector (string): CSS selector of the file input element
• file_path (string): Path to the file to upload
• session_id (string): Session ID

Browser Utilities

browser_wait_for

Wait for an element to reach a specific state or for a timeout.

Parameters:

• selector (string, optional): CSS selector to wait for (empty for just timeout)
• timeout (integer): Maximum time to wait in milliseconds (default: 30000)
• state (string): "visible", "hidden", "attached", or "detached" (default: "visible")
• session_id (string): Session ID

Example:

{
  "selector": ".loading",
  "state": "hidden",
  "timeout": 10000,
  "session_id": "my-session-1"
}

browser_handle_dialog

Handle browser dialogs (alert, confirm, prompt).

Parameters:

• action (string): "accept" or "dismiss" (default: "accept")
• prompt_text (string, optional): Text to enter in prompt dialogs
• session_id (string): Session ID

browser_run_code

Execute JavaScript code in the browser context.

Parameters:

• code (string): JavaScript code to execute
• session_id (string): Session ID

Example:

{
  "code": "return document.title;",
  "session_id": "my-session-1"
}

Browser Inspection

browser_snapshot

Get a snapshot of the current page DOM.

Parameters:

• session_id (string): Session ID

Returns: HTML content of the current page.

browser_take_screenshot

Take a screenshot of the current page.

Parameters:

• full_page (boolean): Whether to take a screenshot of the full scrollable page (default: false)
• session_id (string): Session ID
• path (string, optional): Path to save the screenshot

Returns: Base64-encoded screenshot image.

browser_resize

Resize the browser viewport.

Parameters:

• width (integer): Viewport width in pixels (default: 1920)
• height (integer): Viewport height in pixels (default: 1080)
• session_id (string): Session ID

Session Management

close_session

Close a browser session and free resources.

Parameters:

• session_id (string): Session ID to close

📝 Usage Example

1. Connecting to the MCP Server

Deploy the Actor to Apify and connect to the endpoint:

https://<your-actor-id>.apify.actor/mcp

Use the Streamable HTTP transport and pass your Apify API token in the Authorization header:

Authorization: Bearer <YOUR_APIFY_API_TOKEN>

2. Example Workflow

Step 1: Navigate to a webpage

{
  "tool": "browser_navigate",
  "arguments": {
    "url": "https://example.com",
    "session_id": "session-123"
  }
}

Step 2: Wait for content to load

{
  "tool": "browser_wait_for",
  "arguments": {
    "selector": ".main-content",
    "state": "visible",
    "session_id": "session-123"
  }
}

Step 3: Extract data

{
  "tool": "find_elements",
  "arguments": {
    "selector": "h2.product-title",
    "selector_type": "css",
    "session_id": "session-123"
  }
}

Step 4: Take a screenshot

{
  "tool": "browser_take_screenshot",
  "arguments": {
    "full_page": true,
    "session_id": "session-123"
  }
}

Step 5: Close the session

{
  "tool": "close_session",
  "arguments": {
    "session_id": "session-123"
  }
}

🏷️ Session Management

Sessions are automatically managed. Provide a session_id to maintain browser context across multiple tool calls. This allows you to:

• Navigate to a page once and perform multiple operations
• Maintain cookies, localStorage, and authentication state
• Build complex automation workflows

Session Timeout: Sessions automatically close after 300 seconds (5 minutes) of inactivity by default. This can be configured via the SESSION_TIMEOUT_SECS environment variable.

�️ Cloudflare & Bot Protection

This Actor includes powerful features to bypass Cloudflare and other anti-bot protections:

Automatic Cloudflare Solver

The solve_cloudflare parameter automatically detects and solves Cloudflare challenges:

{
  "tool": "fetch_url",
  "arguments": {
    "url": "https://protected-site.com",
    "solve_cloudflare": true,
    "session_id": "my-session"
  }
}

Advanced Stealth Options

Combine multiple stealth techniques for maximum protection bypass:

• solve_cloudflare: Automatically solve Cloudflare challenges
• block_webrtc: Block WebRTC to prevent IP leak detection
• real_chrome: Use real Chrome browser instead of Chromium (harder to detect)
• hide_canvas: Hide canvas fingerprinting to avoid detection
• google_search: Simulate traffic coming from Google search (more trustworthy)

Full Protection Example:

{
  "tool": "fetch_url",
  "arguments": {
    "url": "https://highly-protected-site.com",
    "fetcher_type": "stealthy",
    "solve_cloudflare": true,
    "block_webrtc": true,
    "real_chrome": true,
    "hide_canvas": true,
    "google_search": true,
    "session_id": "my-session"
  }
}

These options work with both fetch_url and browser_navigate tools when using the stealthy fetcher.

�💰 Pricing

This Actor uses the Pay Per Event monetization model. Each tool call is charged according to the pricing defined in the Actor's configuration.

Event charged: tool-call

🛠️ Fetcher Types Explained

Simple Fetcher

• Basic HTTP requests
• Fastest performance
• No JavaScript execution
• Best for: Static HTML pages, APIs

Dynamic Fetcher

• Browser-based (Playwright)
• JavaScript execution
• Moderate anti-detection
• Best for: JavaScript-heavy sites

Stealthy Fetcher (Recommended)

• Advanced anti-detection browser
• Stealth plugins enabled
• Human-like behavior
• Best for: Protected sites, anti-bot systems

🚀 Running Locally

# Install dependencies
pip install -r requirements.txt

# Set environment variables
$env:APIFY_META_ORIGIN = "STANDBY"

# Run the server
python -m src

The server will start at http://localhost:3000/mcp

📦 Deployment

# Login to Apify
apify login

# Push to Apify platform
apify push

🔗 Resources

• Model Context Protocol
• Apify Documentation
• FastMCP

📄 License

This Actor is available under the Apache License 2.0.

🤝 Support

For issues, questions, or contributions, please visit the Apify Console.

---

Built with ❤️ using Scrapling, FastMCP, and Apify