Pydoll MCP Server
yurilopes/pydoll-mcp-server
Automação de browser com API orientada a agentes via MCP
Ver no GitHubServidor MCP para automação de browser baseado na biblioteca Pydoll, oferecendo uma alternativa local ao Playwright MCP Server com API orientada a agentes. Fornece ferramentas para observação de páginas, seleção de elementos, navegação, captura de screenshots e execução de JavaScript com controle sobre iframes e shadow DOM.
Instalação
npx convez-ai yurilopes/pydoll-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de testes web com agentes IA
- Web scraping inteligente e observação de páginas
- Interação programática com interfaces web complexas
Veredito

Projeto maduro em alpha com arquitetura bem pensada para agentes. Excelente para casos que exigem automação browser localmente controlada, mas requer Python 3.10+ e Chrome/Chromium instalado.
README
A tradução para o português deste README ainda está na fila.
Pydoll MCP Server
MCP server for browser automation built on the Pydoll library.
This project offers a local alternative to the Playwright MCP Server, with its own agent-oriented API built on Pydoll. It does not copy the Playwright API. It provides a predictable layer for agents: observe pages, choose elements, act by element_id, navigate, capture screenshots, execute JavaScript with limits, and handle iframes and shadow DOM.
Status
Experimental alpha (v0.3.0a1). HTTP on 127.0.0.1 is the primary transport. stdio transport is available as an option (--transport stdio).
Endpoints:
/health- Health check (no auth)/mcp- Streamable HTTP MCP (bearer token required)/sse- Server-Sent Events (bearer token required)
Requirements
- Python
>=3.10 - Chrome or Chromium installed
- Pydoll
>=2.23.0
Contributors must follow the quality gates and engineering conventions in
docs/development.md.
Installation
python -m pip install -e ".[dev]"
For release distribution:
pip install pydoll-mcp-server
Running
Set a token before starting:
# Windows (PowerShell)
$env:PYDOLL_MCP_AUTH_TOKEN = "your-secret-token"
# Linux / macOS
export PYDOLL_MCP_AUTH_TOKEN="your-secret-token"
Start the server (HTTP, the default):
python -m pydoll_mcp_server.cli --host 127.0.0.1 --port 8765
Or via stdio:
python -m pydoll_mcp_server.cli --transport stdio
Endpoints:
GET http://127.0.0.1:8765/health- public health check, no tokenPOST http://127.0.0.1:8765/mcp/- Streamable HTTP MCP, with bearer tokenGET http://127.0.0.1:8765/sse/- SSE MCP, with bearer token
MCP clients must send:
Authorization: Bearer <PYDOLL_MCP_AUTH_TOKEN>
PYDOLL_MCP_ALLOW_NO_AUTH=true should only be used in isolated development.
MCP Tools
Health and diagnostics:
health_checkserver_statusdiagnostics_snapshottrace_start,trace_stop,trace_get,trace_cleanup
Lifecycle:
browser_launchbrowser_listbrowser_closebrowser_attachtab_listtab_activatetab_closetab_recovertab_new,tab_duplicate,tab_health_check,tab_recreatedialog_list,dialog_handle,popup_prepare,popup_waitproxy_validate,proxy_get
browser_launch accepts an optional proxy_server using http, https,
socks4, or socks5, plus an optional proxy_bypass_list. Proxy credentials
may be embedded for Pydoll authentication, but MCP responses and browser
listings expose only sanitized metadata without usernames or passwords. Proxy
configuration is immutable after browser launch.
Navigation:
page_gotopage_reloadpage_backpage_forwardpage_waitpage_wait_for_url,page_wait_for_functionpage_wait_for_text,page_wait_text_gone,page_wait_for_selector,page_wait_for_network_idlepage_scroll,page_scroll_to
Observation:
page_get_textpage_get_treepage_get_tree_deeppage_get_interactive_summarypage_screenshotpage_snapshot,page_diffpage_get_accessibility_tree,frame_list,frame_snapshotpage_print_pdf
Elements:
element_findelement_find_deepelement_clickelement_click_by_text,element_click_center,mouse_clickelement_typeelement_fillelement_fill_and_verify,element_wait_valueelement_get_textelement_get_attributeelement_screenshotelement_get_state,element_wait_for_stateelement_select_option,element_check,element_uncheckelement_hover,element_scroll_into_view,keyboard_press- semantic finders by role, text, label, placeholder, and test ID
form_snapshot,form_errorscombobox_get_options,combobox_type_and_select,combobox_select_option
JavaScript and advanced helpers:
js_evaluate_readonlyjs_evaluateuser_agent_setviewport_setcookies_getcookies_setstorage_getstorage_setdownload_expectdownload_prepare,download_wait,download_list,download_get_infoupload_filesfile_upload_state,artifact_get_paths,artifact_importoperation_cancel
Network inspection:
network_enablenetwork_disablenetwork_listnetwork_get_responsenetwork_summary,network_clearnetwork_wait_for_request,network_wait_for_response
Console inspection:
console_enable,console_disable,console_list
Agent-friendly model
page_get_tree returns a compact, limited tree by default. It prioritizes visible body content and hides head, script, meta, style, link, and invisible nodes unless include_head=true or include_invisible=true is set. Interactive nodes receive element_id, selector_hint, xpath_hint, actionable, and resolution_confidence. An agent can observe the tree and call element_click or element_fill directly with the element_id, without calling element_find first.
page_get_interactive_summary is the recommended first observation for modern frontend apps. It returns visible controls with roles, names, labels, nearby section context, bounding boxes, selector hints, enabled/editable state, and cached element_id values.
For React-like forms and custom controls, prefer element_fill, element_fill_and_verify, combobox_type_and_select, element_click_by_text, and condition waits before using custom JavaScript. js_evaluate and js_evaluate_readonly return structured JSON values directly in value; clients should not parse value as a JSON string.
page_get_tree_deep is the recommended option when the page uses iframes or shadow DOM. It is more expensive, has its own timeout, and returns:
frame_pathshadow_pathpartialerrors- visibility and interaction metadata when available
The alpha covers simple iframes, same-origin nested iframes, and open shadow DOM. Closed shadow roots and complex cross-origin cases still require additional validation.
Security
- Bearer token is required by default.
- The default bind must remain
127.0.0.1. - Free
execute_cdp_cmdis not exposed. - Operating system commands are not exposed.
- Arbitrary filesystem read or write is not exposed.
- Navigation to
file://is blocked completely. Serve local fixtures through loopback HTTP. - Screenshots, downloads, and uploads use controlled directories or an allowlist.
- Cookies and storage are redacted by default on read.
- Sensitive attributes such as tokens, passwords, and cookies are redacted.
- Logs must redact bearer tokens, cookies, authorization headers, and sensitive fields.
- Proxy credentials are never returned or stored in browser metadata.
js_evaluate is a sensitive tool:
- Requires explicit
tab_id. - Uses a short timeout by default.
- Limits code and result size.
- Logs a summarized audit with hash, duration, and size.
- Must not log full code or full results.
- Warns or blocks dangerous patterns, depending on mode.
- May be disabled in the future via a safe-mode configuration.
js_evaluate_readonly is preferred for inspection, but should also be treated as sensitive.
Runtime directories
Runtime data is stored outside the repository by default:
- Windows:
%LOCALAPPDATA%\pydoll-mcp-server - macOS:
~/Library/Application Support/pydoll-mcp-server - Linux:
~/.local/share/pydoll-mcp-server
Expected subdirectories:
profiles/tmp/downloads/artifacts/logs/
Vendored Pydoll documentation
Vendored Pydoll documentation is available at:
references/pydoll-docs/
Do not mix vendored documentation with MCP server code.
Testing
Core gates:
python -m pytest -q
python -m ruff check .
python -m ruff format --check .
python -m mypy --strict src tests
python -m pyright
python -m pytest -m mcp_e2e -q
python -m pytest -m browser_smoke -q
python -m build
Useful test suites by area:
python -m pytest tests/contract -q
python -m pytest tests/unit/test_concurrency.py -q
python -m pytest tests/unit/test_security.py tests/unit/test_files_security.py -q
python -m pytest tests/p2/ -q
browser_smoke opens Chrome/Chromium headless and validates real flows with local fixtures.
Known limitations
- Console inspection depends on Chromium Runtime events and may return
UNSUPPORTEDwhen unavailable. browser_attachdoes not support reconnection across server sessions (returnsUNSUPPORTED).- JavaScript dialogs can block the originating browser command; handle them from an independent MCP request.
- Closed shadow roots and complex OOPIFs still require dedicated validation.
- Deep traversal is more expensive than
page_get_treeand should be used explicitly. - Downloads depend on Pydoll's
expect_downloadflow and must remain in the controlled runtime dir. - Uploads must only use paths allowed by the allowlist.
operation_cancelcurrently applies to waits that receive an explicit caller-providedoperation_id.
License
MIT