← Back to directory
D

DrissionPage MCP Server

Community
Local browser automation MCP server powered by DrissionPage
GitHub source repository ↗
★ 488 Stars Category · Browser Very popular
64FMRS · C

A community-maintained local browser automation MCP server built on DrissionPage that exposes 69 typed atomic tools over stdio, covering navigation, tabs, element interaction, screenshots, frames and Shadow DOM, cookies and storage, network observation, waits, and console logs. It is structured-first with optional coordinate and deterministic natural pointer motion, and it redacts URLs, credentials, headers, cookies, network bodies, and related metadata by default. All tools load by default, there are zero prompts, and the only resource is a static optional-Skills catalog. It is beta software under Apache 2.0 and is not an upstream official project; real behavior depends on the local Chrome/Chromium and target sites, so use a dedicated browser profile and verify results.

Reliability
11/20
Security and permissions
12/20
Maintenance
12/20
Documentation
15/20
Setup experience
14/20
Read the FMRS scoring method →

DrissionPage MCP Server is a local Model Context Protocol server that exposes DrissionPage's browser automation capabilities as 69 typed, atomic tools to Codex CLI/IDE, Claude Code, Claude Desktop, Cursor, and other MCP clients. It runs over stdio, installs from the PyPI package drissionpage-mcp, and requires Python 3.10+ plus a local Chrome or Chromium. The design is structured-first and vision-ready: use DOM structure when reliable selectors exist, and coordinates with either direct or bounded deterministic natural pointer motion for canvas, map, chart, and other visual-only surfaces. The server executes exactly the requested browser operation; site flows, component-library adaptation, challenge handling, and business policy belong to the client or optional Skills. It exposes zero MCP prompts and one static optional-Skills catalog resource. The project is in beta, licensed under Apache 2.0, and maintained by a community author rather than the upstream product owner.

Tools

page_navigate
Navigate to any URL; target an existing tab_id, or combine new_tab=true with optional background, new_window, or new_context; observe returns a change summary
page_navigate_with_http_auth
Navigate through a scoped HTTP auth challenge in a dedicated disposable Chromium context without returning credentials
page_go_back
Navigate backward in browser history
page_go_forward
Navigate forward in browser history
page_refresh
Reload the current page
tab_list
List open browser tabs with stable MCP tab IDs
tab_switch
Switch to a tab returned by tab_list
tab_close
Reject new work, drain in-flight actions, then close one tab without closing the whole browser
element_find
Find one element by CSS selector or XPath; bare selectors like h1 are treated as CSS
element_find_all
Extract bounded repeated elements with text, attributes, and recommended selectors
element_click
Click any element with additive left/right/middle and single/double-click semantics
element_click_and_download
Correlate one selector, coordinate, or keyboard trigger with one integrity-checked artifact under DP_MCP_DOWNLOAD_ROOT
element_type
Input text into elements
element_upload_file
Use element_upload_file(paths=[...]) to upload files from DP_MCP_UPLOAD_ROOT to input[type=file]
element_click_and_upload
Arm Chromium's file chooser, click its trigger, inject approved files, and clean interception without an operating-system picker
element_scroll_into_view
Bring an element into the viewport before acting
element_hover
Hover an element to trigger menu or tooltip states
element_select
Select an option by value, text, or index
element_check
Check or uncheck checkbox/radio controls
element_get_text
Get element or page text
element_get_attribute
Get an HTML attribute
element_get_property
Get a live DOM property such as an input value
element_get_html
Get element or page HTML
element_state_get
Read live DrissionPage state flags and document/viewport geometry for one element
page_screenshot
Capture an inline full-page or viewport screenshot
page_screenshot_save
Save a screenshot under DP_MCP_SCREENSHOT_ROOT
page_export_artifact
Generate a managed PDF or MHTML artifact under DP_MCP_ARTIFACT_ROOT with SHA-256 and receipt evidence
page_snapshot
Return a bounded page outline with headings, links, buttons, inputs, forms, and selector recommendations
page_accessibility_snapshot
Return a bounded Chromium accessibility tree for the page or a scoped element, with field values redacted unless explicitly requested
page_observe
Return a compact page fingerprint with URL, title, counts, visible text samples, active element, and recent console summary
page_evaluate
Run bounded JavaScript in the current page and return a JSON-safe result
page_scroll
Use page_scroll(pixels=...) for relative scrolling, or pass x/y for an absolute position
keyboard_press
Send keys to the active element or page without echoing the input in results
page_resize
Adjust the browser window
page_pointer_move
Move to exact viewport CSS coordinates with direct or bounded deterministic natural motion
page_pointer_drag
Perform one failure-safe coordinate drag through up to six optional ordered waypoints with the selected profile
page_pointer_drag_element
Resolve source and destination geometry immediately before dragging; supports CSS/XPath in the top document or one same-origin iframe, plus CSS paths through nested open Shadow DOM hosts
page_click_xy
Move with direct or natural motion, optionally wait for an explicit delay, then press and release at the exact target
page_close
Close the browser
page_get_url
Get the current URL
page_dialog_observe
Wait for and inspect a pending native alert, confirm, or prompt without handling it
page_dialog_respond
Use page_dialog_respond(action="accept") (or "dismiss") for one pending alert, confirm, or prompt
frame_list
List iframe/frame contexts without changing global frame state
frame_snapshot
Use frame_snapshot(frame_selector="...") or frame_index to inspect one iframe with bounded outline data
frame_find
Find an element inside a selected iframe
shadow_find
Find one element inside a shadow root exposed by the current supported DrissionPage runtime, including tested closed roots
shadow_find_all
Extract repeated elements from a DrissionPage-exposed shadow root
browser_headers_set
Replace extra request headers and return names with redacted values; an empty object clears them
browser_user_agent_set
Override the user agent and optional platform, returning both the accepted and previous user agents
browser_cache_clear
Clear HTTP cache while preserving Cookies, localStorage, and sessionStorage
browser_permission_get
Query one browser permission for the current document origin without opening an OS prompt
browser_permission_set
Use browser_permission_set(setting="granted") (or "denied"/"prompt") for an exact origin or the current Chromium context
browser_permissions_reset
Reset permission overrides for the current Chromium context
browser_cookies_get
Read normalized cookies with values redacted by default
browser_cookies_set
Set up to 100 cookies in one call and return accepted metadata with redacted values
browser_cookies_delete
Delete one named cookie with optional URL/domain/path scope
browser_cookies_clear
Clear all browser cookies
storage_get
Read localStorage/sessionStorage by key or as a map, with values redacted unless include_values=true
storage_set
Set one localStorage/sessionStorage item without echoing the value
storage_clear
Clear one storage key or an entire storage area
page_console_logs
Read bounded browser console messages with level filtering, cursor pagination, and limits
wait_for_element
Wait for an element to appear (with timeout)
wait_for_url
Use wait_for_url(url_pattern="...") until the current URL contains the supplied text
wait_until
Use wait_until(condition="text_contains", value="...") or another documented condition/value pair
wait_time
Delay execution
network_listen_start
Start bounded HTTP/XHR/Fetch observation through DrissionPage
network_listen_wait
Wait for bounded packet metadata with optional redacted headers or body excerpts
network_listen_stop
Stop observation and optionally clear queued packets
network_blocked_urls_set
Use network_blocked_urls_set(urls=[...]) to replace blocked URL patterns; an empty list clears them

Setup

  1. Install or update your client (for example Codex CLI on macOS/Linux: curl -fsSL https://chatgpt.com/codex/install.sh | sh). 2. Install from PyPI with python -m pip install -U "drissionpage-mcp>=0.8.8". 3. Verify the package and environment with drissionpage-mcp --version and drissionpage-mcp doctor; doctor must report mcp_supported and mcp_server_wiring as ok, and --launch-browser adds a browser startup check. 4. Configure the client: for Codex, add [mcp_servers.drissionpage] with command = "drissionpage-mcp", startup_timeout_sec = 20, and tool_timeout_sec = 60 to ~/.codex/config.toml (or .codex/config.toml in a trusted project); for JSON clients (Claude Code, Cursor, Claude Desktop), add {"mcpServers": {"drissionpage": {"command": "drissionpage-mcp"}}} to the client's config file. 5. Restart the client; in Codex run /mcp or codex mcp list to verify. If a GUI-launched client cannot see your shell PATH or virtualenv, use the absolute Python executable as command with args = ["-m", "drissionpage_mcp.cli"].
claude_desktop_config.json
{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

Fit and risk

Best for

  • Developers already using Codex CLI/IDE, Claude Code, Claude Desktop, or Cursor who want to drive a local browser
  • Automation that needs both DOM-selector work and coordinate interaction on visual surfaces
  • Teams wanting a lightweight Python 3.10+ browser automation option using local Chrome/Chromium
  • Local workflows that need no external API credentials, including authorized testing and accessibility work

Not for

  • Users expecting built-in site-specific workflows, component-library adaptation, or challenge handling (these live in the client or optional Skills)
  • Environments without Chrome/Chromium or without Python 3.10+
  • Users who need a cloud-hosted browser or remote execution environment
  • Production-critical scenarios that require official vendor support or an SLA

Required permissions

  • Local browser control: open tabs, navigate to any reachable URL, run bounded JavaScript
  • Read and write browser Cookies, localStorage, and sessionStorage
  • Read and modify request headers, user agent, HTTP cache, and browser permissions
  • File upload and download (bounded by DP_MCP_UPLOAD_ROOT and DP_MCP_DOWNLOAD_ROOT), plus screenshot and PDF/MHTML artifact writes (bounded by DP_MCP_SCREENSHOT_ROOT and DP_MCP_ARTIFACT_ROOT)
  • Access to authenticated sessions and page content in the local browser

Risks and side effects

  • The local browser may hold authenticated sessions, cookies, downloads, and page data, so mistakes can affect real accounts or production systems
  • It can open and interact with any site reachable from the local machine, risking misuse or violation of site terms
  • Coordinate-based interaction depends on the model's reading of screenshot coordinates and can click the wrong place, so observe and verify results
  • Downloads, uploads, and exported artifacts write to the local file system, so review directories and content boundaries
  • DP_NO_SANDBOX=1 disables the Chrome sandbox and should be reserved for restricted container or root environments
  • The project is in beta; real browser behavior depends on the local Chrome/Chromium and target sites

Troubleshooting

  1. If tools do not load, run drissionpage-mcp --version and confirm output such as drissionpage-mcp 0.8.8
  2. Run drissionpage-mcp doctor and confirm mcp_supported and mcp_server_wiring are ok; version output alone does not prove the client can initialize the server
  3. Browser issues: check installation with which google-chrome (Linux) or which chromium (macOS); use CHROME_PATH to point at a custom browser and DP_HEADLESS=1 for headless runs
  4. If Codex cannot find the server, run codex mcp list or /mcp in the TUI; for JSON clients verify the config path and JSON syntax and restart the client
  5. If a GUI-launched client cannot see your shell PATH or virtualenv, use the absolute Python executable and args ["-m", "drissionpage_mcp.cli"]
  6. For debug logs use drissionpage-mcp --log-level DEBUG and consult docs/troubleshooting.md
  7. Validate a checkout with python -m pytest tests/ or DP_HEADLESS=1 python playground/run_mcp_lab.py --all --json

Use cases

Automated testing of web applications
Scraping structured data from websites
Filling out and submitting forms
Monitoring pages for updates or changes
Capturing and verifying page state with screenshots
Analyzing web content programmatically
Coordinate interaction with canvas, map, chart, and other visual-only surfaces

Supported clients

Claude DesktopFull support
Claude CodeFull support
CursorFull support
Codex CLI/IDEFull support
VS CodePartial support