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.