DrissionPage MCP Server

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

Official Repositories: GitHub | GitCode

English Version | 中文版本

🖱️ Vision-Guided Human–Computer Interaction

DrissionPage MCP 0.5.8 adds a major new interaction layer for multimodal AI: it can turn a vision model's viewport coordinate into a complete, physically plausible pointer action chain—not just a raw teleport-and-click.

One MCP call connects visual understanding to real browser interaction. The model identifies where to act; DrissionPage MCP handles how the pointer gets there and performs the click.

Screenshot / page observation
        ↓
Multimodal model identifies viewport coordinates
        ↓
page_click_xy(profile="natural")
        ↓
Cubic Bézier motion → reaction pause → press → hold → release
        ↓
Observe and verify the resulting page state

What makes this interaction layer different?

• Natural pointer dynamics: 20–35 cubic Bézier movement steps instead of coordinate teleportation.
• Human-like timing: 8–25ms point intervals, smoothstep ease-in-out, and a 100–300ms reaction pause after arrival.
• Physical click semantics: 50–120ms press duration with correct Chromium CDP button state for left, right, and middle clicks.
• Controlled micro-motion: bounded ±0.5 CSS-pixel intermediate jitter while the final point remains exact.
• Failure-safe execution: a pressed button is always released if the action chain is interrupted.
• Model-readable evidence: results include the chosen profile, start and target coordinates, step count, reaction delay, hold duration, and planned duration.

This makes vision-guided operation practical for canvas controls, visual editors, maps, charts, non-semantic widgets, responsive interfaces, and other surfaces where selectors or accessibility metadata are incomplete. Structured DOM automation remains the preferred path when reliable selectors are available; the vision interaction layer expands what an MCP agent can operate when they are not.

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

Designed for legitimate UI automation, testing, accessibility workflows, and technical research. Security or anti-automation challenge completion is not offered as a guaranteed supported capability.

🧭 Client Setup Navigation

• Vision-guided human–computer interaction
• Install + screenshot walkthrough
• Codex CLI/IDE quick setup
• Codex CLI/IDE integration example
• Claude Code setup
• Cursor setup
• Claude Desktop setup
• Troubleshooting

🚀 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.

Structured, deterministic automation remains the default through 52 tools plus MCP Resources/Prompts. When selectors or accessibility metadata are insufficient, 0.5.8 also provides an optional vision-guided human–computer interaction layer that converts viewport coordinates into natural Chromium pointer action chains, 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
• Vision-Ready Interaction: Converts multimodal model coordinates into natural pointer movement and physically timed clicks
• 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/prompt, 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.
• 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

# Install from PyPI
python -m pip install -U drissionpage-mcp

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

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

📦 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.

1. Edit Codex configuration:

   • User-level: ~/.codex/config.toml
   • Project-level: .codex/config.toml inside a trusted project

2. Add this configuration:

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

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

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

🎯 Quick Examples

Navigate and Screenshot

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

Search and Extract

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

Form Automation

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

Data Scraping

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

🛠️ 52 Powerful Tools + MCP Resources/Prompts

🌐 Navigation (4 tools)

• page_navigate - Navigate to any URL; optionally open it in a new tab with new_tab or return an observe change summary
• page_go_back / page_go_forward - 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 - Close one tab without closing the whole browser

🎯 Element Interaction & Extraction (13 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
• element_type - Input text into elements
• element_upload_file - Upload files from DP_MCP_UPLOAD_ROOT to input[type=file]
• 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

🧾 Form Operations (1 tool)

• form_inspect - Inspect forms and controls with labels, selectors, requirements, options, and safe optional values

📸 Page Operations (11 tools)

• page_screenshot - Capture an inline full-page or viewport screenshot
• page_screenshot_save - Save