DrissionPage MCP Server

Professional browser automation for Codex, Claude Code, and MCP clients, powered by DrissionPage.

DrissionPage is a Python web automation library built around direct Chromium/CDP control with requests-style HTTP session support. This server exposes its browser-facing capabilities as typed, atomic MCP tools.

Open the interactive Browser Lab to replay bounded natural pointer motion, drag controls, and verify observable state.

Official Repositories: GitHub | GitCode

English Version | 中文版本

🖱️ Atomic Browser Control with Natural Pointer Motion

DrissionPage MCP 0.8.8 exposes 69 typed browser capabilities. The MCP server provides accurate low-level observation and interaction; the client or an optional Skill composes those capabilities for a site, component library, challenge, or business workflow.

The model decides what to do; the MCP executes the requested browser operation exactly.

text

Screenshot / page observation
        ↓
Multimodal model identifies viewport coordinates
        ↓
page_click_xy(x=442, y=369, profile="natural")
        ↓
24-step eased cubic path → exact target → press → release
        ↓
Observe and verify the resulting page state

Core interaction guarantees

Two bounded profiles: direct emits one exact move; natural emits a deterministic 24-step eased cubic path with reproducible 8-14ms intervals and exact final arrival.
No hidden randomness: the same start, target, and profile produce the same path; there is no jitter, overshoot, or anti-detection logic. Pointer position is stateful, so a repeated call can begin from the previous endpoint.
Explicit sequences: click is the selected move profile, optional caller-specified delay, press, release; drag keeps one press across the selected path and ordered waypoints.
Failure-safe input: a pressed pointer button is released if execution fails after the press.
Fresh browser evidence: selector geometry is resolved immediately before selector-backed drag operations.
Typed results: outputs report the executed coordinates, button, step count, and explicit delay metadata.

Use structured DOM targets when reliable selectors exist. Use coordinates, natural motion, and explicit drag waypoints for canvas controls, editors, maps, charts, and other visual-only surfaces. Component-specific target discovery, challenge observation, multi-click sequencing, login procedures, and other business policy belong in the client or an optional Skill.

config.json

{
  "x": 442,
  "y": 369,
  "profile": "natural",
  "button": "left",
  "element": "visually identified control"
}

Designed for authorized browser automation, testing, accessibility workflows, and technical research. The core does not provide challenge-specific or site-specific workflows.

🚀 What is DrissionPage MCP?

DrissionPage MCP Server is a local Model Context Protocol (MCP) server that brings DrissionPage browser automation tools to Codex CLI/IDE, Claude Code, Claude Desktop, and other MCP clients.

The standalone server exposes 69 typed tools, zero MCP prompts, and one static optional-Skills catalog resource. Version 0.8.8 keeps that registry stable while adding correlated network-listener generations, explicit packet cursors, timeout evidence, cancellation recovery, and tab-owned cleanup. Every tool loads by default; there is no capability profile or opt-in full mode. Models compose these atomic capabilities, while reusable challenge and site procedures live outside the distribution as optional Skills. Browser execution is powered by DrissionPage.

🌟 Why Choose DrissionPage MCP?

Structured-First, Vision-Ready: Uses DOM structure when available and multimodal coordinates when visual interaction is the better tool
Deterministic: Reliable element selection with CSS/XPath normalization for LLM-friendly selectors
Natural Pointer Motion: Offers exact direct movement and a bounded deterministic 24-step eased trajectory from the same atomic tools
Fast & Lightweight: Built on DrissionPage's efficient engine with minimal overhead
Type-Safe: Full type hints and Pydantic validation for all tools
Open-source Friendly: Includes compatibility notes, troubleshooting, and CI checks for maintainable contributions
Easy Integration: Simple pip install + Codex TOML or MCP JSON configuration

✅ Quality and Real-World Validation

DrissionPage MCP is backed by a strict regression suite and browser-backed scenario checks:

Strict automated tests: unit, protocol, schema snapshot, response-contract, resource, release-metadata, security-policy, browser-integration, and coverage checks run in CI.
95% coverage floor: CI enforces the current 95% coverage threshold and uploads coverage reports.
Real browser verification: Chrome/Chromium-backed integration tests exercise the same MCP tools exposed to clients.
Document-boundary verification: focused browser tests prove cross-origin OOPIF reads and DrissionPage-exposed closed Shadow DOM lookup without JavaScript piercing fallbacks.
Challenge-surface verification: local fixtures cover normal, hidden, off-viewport, delayed, and CSS 3D cross-origin widgets; official Turnstile dummy keys cover visible, invisible, pass, fail, and forced-interactive callbacks without retaining tokens.
Scenario validation: the playground MCP Lab covers realistic forms, commerce pages, social feeds, timelines, dynamic waits, iframe cases, and recovery paths without depending on public demo websites.

⚡ First Success Path

bash

# Install or update Codex CLI (macOS/Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Install from PyPI
python -m pip install -U "drissionpage-mcp>=0.8.8"

# Verify package and environment
drissionpage-mcp --version
drissionpage-mcp doctor

The official installer updates an existing Codex CLI installation as well. For Windows and the Codex desktop app, see the official Codex CLI and app documentation.

Then add the Codex or MCP client configuration below and restart your client.

pip install drissionpage-mcp

drissionpage-mcp doctor — all checks green

📦 Setup in Codex CLI/IDE (30 seconds)

Codex supports local stdio MCP servers through config.toml; the CLI and IDE extension share the same MCP configuration.

Edit Codex configuration:
- User-level: ~/.codex/config.toml
- Project-level: .codex/config.toml inside a trusted project

Add this configuration:

toml

[mcp_servers.drissionpage]
command = "drissionpage-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60

Restart Codex. In the TUI, run /mcp; from a shell, run codex mcp list.

Codex config.toml

For Claude Code, Claude Desktop, and other JSON-based MCP clients, see Integration Examples.

🎯 Quick Examples

Navigate and Screenshot

Code

"Visit https://example.com and take a screenshot for me"

Search and Extract

Code

"Go to Wikipedia, search for Python, and get the first paragraph"

Form Automation

Code

"Fill out the form at https://httpbin.org/forms/post and submit it"

Data Scraping

Code

"Get the top 10 news headlines from news.ycombinator.com"

🛠️ 69 Typed Browser Tools

All 63 tab-scoped tools accept an optional tab_id. Omit it to capture the MCP current tab once at call start, or pass an MCP/native DrissionPage tab id to target explicitly. Successful tab-scoped results return the resolved MCP tab_id; independent tabs can run concurrently while actions on one tab remain serialized.

🌐 Navigation (5 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 current page

🗂️ Tab Operations (3 tools)

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 Interaction & Extraction (16 tools)

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/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 Operations (18 tools)

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/page without echoing the input in results
page_resize - Adjust 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 browser
page_get_url - Get 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 / Shadow DOM (5 tools)

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 Environment (6 tools)

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/current Chromium context
browser_permissions_reset - Reset permission overrides for the current Chromium context

🍪 Cookies & Storage (7 tools)

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

🧪 Debug / Observability (1 tool)

page_console_logs - Read bounded browser console messages with level filtering, cursor pagination, and limits

⏱️ Wait Operations (4 tools)

wait_for_element - Wait for 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 Control & Observation (4 tools)

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

🧩 Optional Skills Discovery

Resource: drissionpage://skills/catalog
Prompts: none
Repository examples: cross-origin-iframe-probe, turnstile-testing, and xiaohongshu-content-research
Entry point: skills/<skill-name>/SKILL.md; catalog schema v2 includes Skill/MCP versions, required tools, fixture, fixed v0.8.4 source revision, verification status, and SHA-256
Skills are Markdown procedures for the MCP host. They are not Python modules, are not executed by the server, and are excluded from wheel/sdist packages.

Validate a source checkout with python playground/validate_skills.py --json. Install the fixed catalog release from skills-manager@v0.8.4 with python install.py install --client codex --json or python install.py install --client claude --json.

📖 Skills and Reusable Procedures

The MCP core exposes atomic browser operations. Skills provide reusable, reviewable procedures outside the server:

Example Skill	What it demonstrates	Stop boundary
`cross-origin-iframe-probe`	Frame discovery, cross-origin diagnosis, coordinate fallback, and outside verification	Cannot read the inner DOM of a cross-origin iframe
`turnstile-testing`	Cloudflare test fixtures, authorized production challenge interaction, coordinate geometry, and parent-page checks	Use the documented support matrix and verify the resulting page state
`xiaohongshu-content-research`	Bounded read-only note research and the deterministic `social-notes` fixture	Stop on robots, login, captcha, safety page, or rate limit

Read the full Skills guide before publishing a new procedure. Skills must use existing typed tools, collect fresh evidence, verify postconditions, redact secrets, and state unsupported cases. They do not add new MCP tools or override the server's navigation and safety policy. Multi-tab Skills should carry the returned MCP tab_id into later tab-scoped calls rather than relying on mutable current-tab state.

📚 Documentation

Guide	Description
README.md	Installation, tools, and architecture
docs/compatibility.md	Supported Python, DrissionPage, MCP, and browser versions
docs/tool-contract.md	Public MCP tool names, inputs, annotations, and response shape
docs/troubleshooting.md	Doctor command, browser startup, and client setup fixes
CHANGELOG.md	Release notes

🏗️ Architecture

Built with clean, modular design:

Code

DrissionMCP/
├── drissionpage_mcp/
│   ├── cli.py              # Process entry point
│   ├── server.py           # MCP transport and request routing
│   ├── context.py          # Browser and tab lifecycle facade
│   ├── runtime.py          # Operation keys, receipts, artifacts, and capability state
│   ├── tool_outputs.py     # Typed public result contracts
│   ├── browser/            # Focused DrissionPage capabilities and page scripts
│   └── tools/              # 69 typed MCP tool definitions and thin adapters
├── tests/                  # Unit tests
└── playground/             # MCP Lab business-scenario playground

Key Principles:

✅ Type-safe Pydantic models for all tools
✅ Async/await throughout
✅ Clean separation of concerns
✅ Comprehensive error handling
✅ Unit and protocol test coverage for core tool registration/response behavior

🔧 Configuration

Codex CLI / IDE (Recommended)

toml

[mcp_servers.drissionpage]
command = "drissionpage-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60

# Optional browser/runtime environment variables:
# [mcp_servers.drissionpage.env]
# CHROME_PATH = "/custom/path/to/chrome"
# DP_HEADLESS = "1"

You can also add it with the Codex CLI:

bash

codex mcp add drissionpage -- drissionpage-mcp

If Codex/Cursor/Claude Desktop is launched from a GUI and cannot see your shell PATH or virtualenv, use the absolute Python executable instead:

toml

[mcp_servers.drissionpage]
command = "/absolute/path/to/python"
args = ["-m", "drissionpage_mcp.cli"]
startup_timeout_sec = 20
tool_timeout_sec = 60

JSON MCP Clients

config.json

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

Advanced JSON Setup

config.json

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp",
      "args": ["--log-level", "DEBUG"],
      "env": {
        "CHROME_PATH": "/custom/path/to/chrome"
      }
    }
  }
}

Absolute-Python fallback for GUI clients:

config.json

{
  "mcpServers": {
    "drissionpage": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "drissionpage_mcp.cli"],
      "env": {
        "CHROME_PATH": "/custom/path/to/chrome",
        "DP_HEADLESS": "1"
      }
    }
  }
}

📋 Requirements

Python 3.10+ (3.11+ recommended)
Chrome or Chromium browser
Any MCP-compatible client: Codex CLI/IDE, Claude Code, Claude Desktop, Cursor, VS Code, etc.

🧪 Testing

Verify Installation

bash

# Environment diagnostics; add --launch-browser for a browser startup check
drissionpage-mcp doctor
drissionpage-mcp doctor --launch-browser

# Source checkout tests
python -m pip install -e ".[dev]"
python -m pytest tests/

# Coverage report (CI enforces the current 95% floor and uploads coverage.xml)
python -m pytest tests/ --cov=drissionpage_mcp --cov-report=term-missing --cov-report=xml

# Browser-backed MCP Lab scenario checks
DP_HEADLESS=1 python playground/run_mcp_lab.py --all --json

GitHub Actions runs lint, unit, protocol, package, browser integration, and coverage jobs. Codecov is configured through codecov.yml and the CI workflow.

Try It Out

bash

# No-browser MCP registry check
python playground/run_mcp_lab.py --case registry

# Local deterministic site check
python playground/run_mcp_lab.py --case site

# Browser-backed form inspection scenario
DP_HEADLESS=1 python playground/run_mcp_lab.py --case form-inspect

🚀 Use Cases

✅ Automated Testing - Test web applications ✅ Data Scraping - Extract structured data from websites ✅ Form Automation - Fill and submit forms ✅ Monitoring - Check for updates or changes ✅ Screenshot Verification - Capture and verify page state ✅ Content Analysis - Analyze web content programmatically

🐛 Troubleshooting

Tools Not Loading?

bash

drissionpage-mcp --version

Should output the installed package version, for example drissionpage-mcp 0.8.8.

drissionpage-mcp doctor must also report both mcp_supported and mcp_server_wiring as ok; package-version output alone does not prove that an MCP client can initialize the server.

Browser Issues?

bash

# Check browser installation
which google-chrome    # Linux
which chromium         # macOS

Codex / MCP Client Not Finding Server?

Codex: run codex mcp list; in the TUI, run /mcp
JSON clients: verify config file path and JSON syntax
Restart Codex or your MCP client after changes
Check logs: drissionpage-mcp --log-level DEBUG

See docs/troubleshooting.md for the complete troubleshooting guide.

📊 Project Status

Component	Status
Core Features	✅ Complete
Testing	✅ Strict unit/protocol/schema checks plus browser-backed scenarios
Documentation	✅ Setup, compatibility, troubleshooting, and public tool contracts
Package	✅ PyPI metadata and build checks
Status	🟡 Beta; real browser behavior depends on local Chrome/Chromium and target sites

Version: 0.8.8 | License: Apache 2.0 | Maintained: ✅ Active

🗺️ Roadmap

Current (v0.8.8)

📖 Integration Examples

Codex CLI / IDE

toml

[mcp_servers.drissionpage]
command = "drissionpage-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60

Verify with:

bash

codex mcp list

Claude Code

config.json

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

Config file: ~/.config/claude-code/mcp_settings.json (macOS/Linux) or %APPDATA%\claude-code\mcp_settings.json (Windows).

Claude Code mcp_settings.json

Cursor

config.json

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

Config file: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project). You can also add it from Cursor Settings → Tools & MCPs → New MCP Server.

Cursor mcp.json

Cursor Settings — add a new MCP server

Claude Desktop

config.json

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

Once connected, the tools load automatically:

MCP client with DrissionPage tools loaded

🤝 Contributing

Contributions are welcome!

Fork the repository
Create a feature branch
Make focused changes
Run the relevant checks
Submit a pull request

See CONTRIBUTING.md for setup, validation, and compatibility expectations.

🔒 Security

Runs locally in your environment
Uses a local browser that may have access to authenticated sessions, cookies, downloads, and page content
Can open and interact with any site reachable from the local machine
Does not require external API credentials

Best Practices:

Use a dedicated browser profile for sensitive workflows
Review MCP client prompts before allowing actions on authenticated or production systems
Respect website terms of service, robots.txt, and rate limits
See SECURITY.md for reporting and safe-usage guidance

📄 License

Licensed under Apache License 2.0 - see LICENSE

📈 Statistics

🌟 Show Your Support

If you find this project useful, please consider:

⭐ Starring on GitHub
📤 Sharing with your network
💬 Leaving feedback or suggestions
🐛 Reporting issues to help improve

Made with ❤️ by Wukunyun

Ready to automate your workflows? Install now: python -m pip install -U drissionpage-mcp

🆕 Latest Version: v0.8.8

Released on 2026-09-08. This release keeps the 69-tool registry while making network listener lifetimes explicit and recoverable:

network_listen_start returns a new listener_token, lifecycle state, packet cursor, and startup timing for each listener generation.
network_listen_wait accepts the token and reports cumulative consumption, monotonic packet indices, elapsed time, explicit timeout status, and remaining timeout budget.
network_listen_stop rejects stale tokens with LISTENER_NOT_FOUND, preventing an old task from stopping a replacement listener on the same tab.
Cancelled waits preserve packets already removed by DrissionPage, and tab close performs best-effort listener stop/queue cleanup before native teardown.
Real Chromium tests isolate listeners across tabs and run 100 start/stop cycles without active driver or queue residue. The public surface remains 69 tools, zero prompts, and one Skills catalog resource.