CloakBrowser MCP

CloakBrowser MCP is a Python MCP server that lets agents control a CloakBrowser-backed browser from Linux servers, CI jobs, and other environments where a normal desktop browser is not available.

It is designed for three runtime modes:

• headless Linux browsing with no $DISPLAY
• virtual-display browsing through Xvfb when headed browser behavior is needed
• CDP connection to an existing CloakBrowser or Chromium-compatible endpoint

The server exposes browser automation tools over MCP stdio, so clients such as Claude Code can start a session, navigate, inspect pages, interact with forms, manage cookies/storage, and work with multiple tabs.

Upstream

This project is an MCP wrapper and agent-facing extension built on top of CloakHQ/CloakBrowser. CloakBrowser provides the underlying browser launch and anti-detection automation layer; this repository adds the MCP server, tool schema, session lifecycle, Linux headless/virtual-display deployment flow, tests, and agent-oriented documentation around it.

Features

• 28 MCP tools for browser sessions, page interaction, cookies, storage state,

and multi-page workflows.

• Works in headless Linux environments by default.
• Optional Xvfb support for virtual display sessions.
• Optional CDP backend for connecting to an existing browser service.
• CloakBrowser launch options for user agent, viewport, proxy, locale,

timezone, geolocation, humanization, extensions, headers, permissions, and persistent profile/state.

• iframe-aware select support through `browser_select_option(...,

frame_selector="iframe#...")`.

• uv-managed local development and deployment.

Requirements

• Python 3.11 or newer
• uv
• Linux, macOS, or another platform supported by the Python dependencies
• For virtual display mode on Linux: Xvfb

Install uv if needed:

curl -LsSf https://astral.sh/uv/install.sh | sh

For virtual display mode on Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y xvfb

If the runtime does not already have browser binaries available, install the Playwright Chromium browser used by the underlying stack:

uv run python -m playwright install chromium

Installation

Clone the repository and create an isolated uv environment:

git clone https://github.com/SJF-ECNU/CloakBrowserMCP.git
cd CloakBrowserMCP
uv sync --extra dev --no-editable

The project depends on:

• cloakbrowser>=0.4,<1
• mcp[cli]>=1.28,<2
• pyvirtualdisplay>=3,<4

After changing source code, rebuild the installed package used by MCP clients:

uv sync --extra dev --no-editable --reinstall-package cloakbrowser-mcp

Run the MCP Server

Start the stdio MCP server:

uv run --no-editable cloakbrowser-mcp

The process communicates over stdio. It is normally launched by an MCP client rather than run manually in a terminal.

Claude Code Setup

From the repository root, register the server:

claude mcp add --scope user cloakbrowser -- \
  uv --project "$PWD" run --no-editable cloakbrowser-mcp

Then restart Claude Code or reconnect MCP servers. Run /mcp in Claude Code and confirm that cloakbrowser is connected.

If you edit the server code, reinstall the package and reconnect Claude Code:

uv sync --extra dev --no-editable --reinstall-package cloakbrowser-mcp

Claude Code may cache MCP tool schemas for the lifetime of a connection, so a restart/reconnect is recommended after tool signature changes.

Generic MCP Client Config

For clients that read JSON MCP configuration, use an entry like this:

{
  "mcpServers": {
    "cloakbrowser": {
      "command": "uv",
      "args": [
        "--project",
        "/absolute/path/to/CloakBrowserMCP",
        "run",
        "--no-editable",
        "cloakbrowser-mcp"
      ]
    }
  }
}

Replace /absolute/path/to/CloakBrowserMCP with the local checkout path.

Browser Modes

Headless Mode

This is the default and is the best choice for Linux servers without a display:

{
  "display_mode": "headless"
}

Virtual Display Mode

Use this when a target site requires headed browser behavior. If $DISPLAY is already set, the server uses it. Otherwise it starts Xvfb.

{
  "display_mode": "virtual"
}

CDP Mode

Use CDP mode to connect to an existing browser or CloakBrowser service:

{
  "backend": "cdp",
  "cdp_url": "http://127.0.0.1:9222",
  "fingerprint": "agent-session-1"
}

You can also set a default CDP URL:

export CLOAK_MCP_DEFAULT_CDP_URL=http://127.0.0.1:9222

Tool Overview

Session tools:

• browser_start
• browser_close

Page basics:

• browser_navigate
• browser_click
• browser_type
• browser_evaluate
• browser_snapshot
• browser_screenshot

Page operations:

• browser_wait_for_selector
• browser_press
• browser_hover
• browser_select_option
• browser_get_text
• browser_get_attribute
• browser_get_links
• browser_scroll
• browser_reload
• browser_go_back
• browser_go_forward

Context and page management:

• browser_get_cookies
• browser_set_cookies
• browser_clear_cookies
• browser_get_storage_state
• browser_save_storage_state
• browser_new_page
• browser_list_pages
• browser_switch_page
• browser_close_page

Common Workflows

Start and Navigate

{
  "tool": "browser_start",
  "arguments": {
    "display_mode": "headless",
    "viewport": {"width": 1440, "height": 900},
    "locale": "en-US",
    "timezone": "UTC"
  }
}

Then navigate:

{
  "tool": "browser_navigate",
  "arguments": {
    "session_id": "<session_id>",
    "url": "https://example.com",
    "wait_until": "domcontentloaded"
  }
}

Inspect a Page

Use browser_snapshot for URL, title, and visible text. Use browser_get_text for all visible text or a selector-specific text extraction:

{
  "tool": "browser_get_text",
  "arguments": {
    "session_id": "<session_id>",
    "selector": "main"
  }
}

Search or Fill a Form

{
  "tool": "browser_type",
  "arguments": {
    "session_id": "<session_id>",
    "selector": "input[name=q]",
    "text": "CloakBrowser MCP"
  }
}

{
  "tool": "browser_press",
  "arguments": {
    "session_id": "<session_id>",
    "selector": "input[name=q]",
    "key": "Enter"
  }
}

Select an Option inside an iframe

For a normal page-level <select>, omit frame_selector. For a select inside an iframe, pass the iframe selector separately:

{
  "tool": "browser_select_option",
  "arguments": {
    "session_id": "<session_id>",
    "selector": "#size",
    "value": "medium",
    "frame_selector": "iframe#preview"
  }
}

Reuse Login State

Save storage state:

{
  "tool": "browser_save_storage_state",
  "arguments": {
    "session_id": "<session_id>",
    "path": "/tmp/cloak-state.json"
  }
}

Start a new session with that state:

{
  "tool": "browser_start",
  "arguments": {
    "storage_state": "/tmp/cloak-state.json"
  }
}

For durable browser profiles, use profile_dir instead. profile_dir and storage_state are mutually exclusive.

browser_start Options

| Option | Type | Notes | | --- | --- | --- | | backend | string | direct or cdp. Defaults to direct. | | display_mode | string | headless, virtual, or cdp. Defaults to headless. | | headless | bool/null | Overrides headless behavior for direct mode. | | proxy | string/null | Proxy URL forwarded to CloakBrowser. | | locale | string/null | Browser locale, for example en-US. | | timezone | string/null | Browser timezone, for example UTC. | | humanize | bool | Enables CloakBrowser humanized behavior. | | profile_dir | string/null | Persistent profile directory. | | cdp_url | string/null | Required for CDP mode unless env var is set. | | fingerprint | string/null | Added to the CDP URL as a fingerprint query parameter. | | user_agent | string/null | Custom user agent. | | viewport | object/null | Example: {"width": 1440, "height": 900}. | | no_viewport | bool | Sets Playwright viewport to null. | | color_scheme | string/null | light, dark, or no-preference. | | geoip | bool | Forwards CloakBrowser geoip option. | | stealth_args | bool | Defaults to true. | | args | array/null | Extra browser launch args. | | extension_paths | array/null | Browser extension paths. | | human_preset | string | CloakBrowser humanization preset. | | human_config | object/null | CloakBrowser humanization config. | | storage_state | string/object/null | Storage state path or object. | | extra_http_headers | object/null | Extra HTTP headers. | | permissions | array/null | Browser context permissions. |

Environment variables:

• CLOAK_MCP_DEFAULT_DISPLAY_MODE: default display mode when not provided
• CLOAK_MCP_DEFAULT_CDP_URL: default CDP endpoint
• CLOAK_MCP_SCREENSHOT_DIR: screenshot output directory

Development

Install development dependencies:

uv sync --extra dev

Run tests against the source tree:

PYTHONPATH=src uv run pytest -q

Run tests against the installed package:

uv sync --extra dev --no-editable --reinstall-package cloakbrowser-mcp
uv run --no-editable pytest -q

Real browser smoke tests are opt-in:

CLOAK_MCP_RUN_SMOKE=1 uv run --no-editable pytest tests/test_smoke.py -q

Virtual display smoke:

CLOAK_MCP_RUN_VIRTUAL_SMOKE=1 uv run --no-editable pytest tests/test_smoke.py -q

CDP smoke:

CLOAK_MCP_SMOKE_CDP_URL=http://127.0.0.1:9222 \
  uv run --no-editable pytest tests/test_smoke.py -q

Security Notes

Browser automation can access web pages, cookies, local files referenced by the browser profile, and authenticated sessions. Run the MCP server in an environment appropriate for the trust level of the agent and target websites.

Avoid sharing persistent profile_dir or storage_state files with untrusted agents.

License

MIT. See LICENSE.