Drissionpage-MCP-Server

DrissionPage MCP Server · Browser automation for Claude Code, Codex, and MCP clients

412

DrissionPage MCP Server

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

<img src="https://raw.githubusercontent.com/jumodada/Drissionpage-MCP-Server/assets/vision-natural-pointer-demo.gif" width="662" alt="AI vision-directed natural pointer interaction demo"> A new interaction layer for multimodal AI — vision coordinates in, natural pointer action chains out.

Official Repositories: GitHub | GitCode

English Version | 中文版本

🖱️ Vision-Guided Human–Computer Interaction

DrissionPage MCP 0.6.0 provides a complete first-stage 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.

🚀 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 57 tools plus MCP Resources/Prompts. When selectors or accessibility metadata are insufficient, 0.6.0 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.

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

Add this configuration:

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

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"

🛠️ 57 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 (16 tools)

page_screenshot - Capture an inline full-page or viewport screenshot
page_screenshot_save - Save a screenshot under DP_MCP_SCREENSHOT_ROOT
page_snapshot - Return a bounded page outline with headings, links, buttons, inputs, forms, and selector recommendations
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 - Scroll the page by direction or to a position
keyboard_press - Send keys to the active element/page
page_resize - Adjust browser window
page_pointer_move - Move to vision-model viewport coordinates with a natural Bézier path without clicking
page_pointer_drag - Perform one failure-safe natural drag between viewport coordinates
page_detect_challenges - Read-only detection of verification-widget signals for autonomous model routing
page_click_xy_batch - Execute multiple visual coordinate clicks in one bounded autonomous call
page_wait_challenge_result - Poll token length and configurable success/retry/challenge signals without exposing token values
page_click_xy - Convert vision-model viewport coordinates into natural Bézier pointer movement and physically timed clicks
page_close - Close browser
page_get_url - Get current URL

🧱 Frame / Shadow DOM (5 tools)

frame_list - List iframe/frame contexts without changing global frame state
frame_snapshot - Inspect a selected iframe with bounded outline data
frame_find - Find an element inside a selected iframe
shadow_find - Find one element inside an open shadow root
shadow_find_all - Extract repeated elements inside an open shadow root

🍪 Cookies & Storage (4 tools)

browser_cookies_get - Read normalized cookies with values redacted by default
storage_get - Read localStorage/sessionStorage by key or as a map
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 - Wait until the current URL contains text
wait_until - Wait for observable conditions such as clickable, hidden, stable, text, or URL matches
wait_time - Delay execution

🧩 MCP Resources and Prompts

Resources: drissionpage://session/summary, drissionpage://session/history, drissionpage://session/state, drissionpage://session/config, drissionpage://guide/model-usage, drissionpage://page/current, drissionpage://tools/catalog, drissionpage://policy/summary
Prompts: drissionpage_mcp_usage_playbook, browser_navigate_and_summarize, browser_extract_structured_data, browser_fill_form_safely, browser_vision_guided_interaction, browser_debug_page_issue

📚 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:

DrissionMCP/
├── drissionpage_mcp/
│   ├── cli.py              # Entry point
│   ├── server.py           # MCP server
│   ├── context.py          # Browser management
│   ├── response.py         # Response formatting
│   ├── tab.py              # Page operations
│   └── tools/              # 46 automation, tab/frame/shadow, page-understanding, form, debug, and session-state tools
├── 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)

[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:

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:

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

JSON MCP Clients

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

Advanced JSON Setup

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

Absolute-Python fallback for GUI clients:

{
  "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

# 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

# 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?

drissionpage-mcp --version

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

Browser Issues?

# 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.6.0 | License: Apache 2.0 | Maintained: ✅ Active

🗺️ Roadmap

Current (v0.6.0)

52 core automation, tab/frame/shadow, page-understanding, form-inspection, workflow, network-listener, session-state, and console-observability tools with removed alias surface
stdio MCP server integration
Doctor diagnostics for local setup
Stable JSON mirror, structuredContent, and typed per-tool MCP outputSchema
Structured recovery hints in error.details.hints for common failures
Balanced page_snapshot output so link-heavy pages still expose controls and forms
form_inspect read-only form inventory with labels, selectors, requirements, options, and safe optional values
Tab management with tab_list, tab_switch, tab_close, and page_navigate(new_tab=true)
Observable actions with page_observe, page_evaluate, wait_until, and optional observe=true changes on navigation, click, and type
Console observability with page_console_logs, console summary in page_observe, and console change fields in observe=true
Workflow helpers with browser_open_and_snapshot, browser_extract_links, and form_fill_preview
Network listener beta with network_listen_start, network_listen_wait, and network_listen_stop for HTTP/XHR/Fetch observation
Natural page_pointer_move, page_pointer_drag, and page_click_xy action chains with cubic Bézier motion, smoothstep easing, bounded jitter, reaction delay, and realistic button hold time
File upload, scrolling, hover, select/check, keyboard, iframe, shadow DOM, cookie, and storage tools for DrissionPage 4.x
Chrome sandbox remains enabled by default; DP_NO_SANDBOX=1 is reserved for restricted container/root environments
Redacted session history resource and response size metadata for bounded outputs
Opt-in local safety policy for navigation and screenshot paths
Resources, prompts, eval harness, compatibility, and troubleshooting documentation
PyPI distribution

Future (v0.6+)

Promote workflow/network beta contracts toward 0.7.0 after field testing
Optional session persistence beyond redacted state summaries
Proxy support
Network interception

📖 Integration Examples

Codex CLI / IDE

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

Verify with:

codex mcp list

Claude Code

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

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

Cursor

{
  "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.

Claude Desktop

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

Once connected, the tools load automatically:

🤝 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.6.0

Released on 2026-07-13. This release adds autonomous visual orchestration on top of the existing pointer action layer:

Added page_detect_challenges for read-only iframe, script, DOM-container, and hidden-field signal detection with optional viewport screenshot attachment.
Added page_click_xy_batch for up to 25 ordered viewport clicks from one stable visual state, with natural pointer motion, bounded inter-click delays, fail-fast defaults, URL-change protection, and structured per-target results.
Added page_wait_challenge_result for bounded autonomous polling and classification as passed, needs_retry, new_challenge, timeout, or indeterminate; token values are never returned.
Extended wait_until with generic attribute/property equals and non-empty conditions.
Added page_click_xy.delay_before_press_ms as explicit timing control; moving visual targets still require a fresh viewport screenshot and coordinate recomputation.
Claude/GPT guidance now teaches the autonomous loop: detect → viewport screenshot → visual analysis → move/click/batch/drag → poll → classify → fresh-evidence bounded retry.
DrissionPage MCP remains a fully autonomous general browser automation tool. Users can compose these primitives independently for authorized automation and technical exchange; the project does not recommend bypassing human-verification systems and makes no completion guarantee.
The public registry now contains 57 tools while preserving strict schemas, typed results, DrissionPage 4.x support, and existing runtime safety policies.

Repository

jumodada

jumodada/Drissionpage-MCP-Server

Created

January 22, 2026

Updated

July 13, 2026

Language

Python