pydoll-browser-mcp

An MCP server for browser automation built on pydoll (real Chrome/Edge over CDP) with:

• multi-context and multi-tab control,
• per-context proxies (isolated cookies/storage per identity),
• a large tool surface covering navigation, elements, network, storage, devtools, stealth, HTTP-via-browser and a raw cdp_send escape hatch,
• screenshot zoom & coordinates (fork addition): tab_screenshot/element_screenshot accept region=[x1,y1,x2,y2] (viewport CSS pixels), scale (magnification, e.g. 2.0) and grid=[cols,rows] (a labeled coordinate grid drawn on the returned image, ready to read click targets from). Cropping, zooming and the grid happen on the captured bitmap in Python (Pillow) — the page is never scrolled, restyled or injected into; only full_page=True uses CDP captureBeyondViewport. The plain viewport shot is capped in width by PYDOLL_MCP_SCREENSHOT_WIDTH (1280, set 0 to disable).

Note: the PyPI distribution is pydoll-browser-mcp (the older pydoll-mcp name belongs to an unrelated project). The Python import package is pydoll_mcp.

Install / run (no project files needed)

Once published, run it straight from PyPI with uv:

uvx pydoll-browser-mcp

or with pipx:

pipx run pydoll-browser-mcp

Both download the server + dependencies into an isolated environment and run it over stdio, so nothing is added to the user's project directory. To install it permanently:

uv tool install pydoll-browser-mcp     # or: pipx install pydoll-browser-mcp

Development install (this repo)

python -m venv .venv
.venv\Scripts\python -m pip install -e .
.venv\Scripts\python -m pydoll_mcp.server

opencode config

Published (isolated, no project files):

{
  "mcp": {
    "pydoll": {
      "type": "local",
      "command": ["uvx", "pydoll-browser-mcp"],
      "enabled": true
    }
  }
}

Local checkout / venv:

{
  "mcp": {
    "pydoll": {
      "type": "local",
      "command": ["C:\\path\\to\\pydoll-mcp\\.venv\\Scripts\\python.exe", "-m", "pydoll_mcp.server"],
      "environment": { "PYDOLL_MCP_PROFILE": "full", "PYDOLL_MCP_HEADLESS": "true" },
      "enabled": true
    }
  }
}

Profiles

PYDOLL_MCP_PROFILE selects the default tool set: core, balanced (default) or full. balanced = core + network + storage + meta. full also enables input, stealth, devtools, http.

Configuration (environment)

Proxies

context_create(proxy_server="host:port:user:password") gives that context its own egress IP. context_create(proxy_server="http://user:pass@host:port") and socks5://host:port also work. Use proxy_test(proxy_server=...) to verify the egress IP before a run. Note: Chrome does not support authenticated SOCKS5; use an unauthenticated local forwarder for that case.

Session persistence

Use context_storage_state_export / context_storage_state_import to move cookies + localStorage between runs or machines. (Chrome profile-dir persistence is unreliable because pydoll force-stops the process after Browser.close.)

Resilience

Each tab is locked independently, so a hung script or renderer on one tab no longer blocks other tabs or browsers. Scripts are aborted after PYDOLL_MCP_SCRIPT_TIMEOUT seconds (Chrome terminates them first when it can) and oversized results are truncated. tab_info reports alive plus an unresponsive_reason when a tab stops responding, browser_status lists dead_tabs whose CDP connection dropped, and closing a stuck tab (tab_close) always works.

Development

python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"

Test harnesses (require Chrome; some hit the network / use proxies):

.venv\Scripts\python tests\test_imaging.py  # pure screenshot pipeline checks (no browser)
.venv\Scripts\python tests\smoke_live.py    # live screenshot tool checks against headless Chrome
.venv\Scripts\python tests\live_check.py    # every tool category, local fixture
.venv\Scripts\python tests\deep_check.py    # 155 checks, asserts 100% tool coverage
.venv\Scripts\python tests\ultra_check.py   # multi-browser, isolated contexts, persistence, stress
.venv\Scripts\python tests\stdio_check.py   # real MCP stdio handshake
.venv\Scripts\python tests\proxy_check.py   # per-context proxy egress

Publishing

python -m pip install build twine
python -m build
twine check dist/*
twine upload dist/*          # prompts for a PyPI API token (username: __token__)