DrissionPage MCP Server

What is DrissionPage MCP Server about?

Enables AI assistants such as Claude Code, Codex, and other MCP‑compatible clients to perform deterministic, structured browser automation. The server exposes 19 built‑in tools (navigation, element interaction, screenshot, waiting, etc.) through MCP, allowing LLMs to issue precise commands instead of relying on pixel‑based screenshots.

How to use DrissionPage MCP Server?

Install the package from PyPI:

python -m pip install -U drissionpage-mcp

Verify the installation:

drissionpage-mcp --version
drissionpage-mcp doctor       # optional diagnostics

Configure an MCP client (e.g., Codex CLI/IDE): add the following to ~/.codex/config.toml or a project‑level .codex/config.toml:

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

For JSON‑based clients (Claude Code, Claude Desktop, Cursor, etc.) use:

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

Restart the client and invoke the server with /mcp (Codex) or the client’s MCP UI.

Key Features of DrissionPage MCP Server

LLM‑optimized: Works with structured inputs/outputs; no vision model needed.
Deterministic selectors: CSS/XPath normalization guarantees reliable element targeting.
19 ready‑to‑use tools covering navigation, element interaction, page operations, waiting, and resource/prompts.
Type‑safe: Full Pydantic models, async/await implementation, and strict response schemas.
Lightweight & fast: Built on the high‑performance DrissionPage engine.
Cross‑client compatibility: Works with Codex CLI/IDE, Claude Code, Claude Desktop, Cursor, VS Code, etc.
Diagnostic “doctor” command for environment checks and optional browser launch testing.

Use Cases

Automated testing of web applications via LLM‑driven scripts.
Data scraping: Extract structured information such as headlines, tables, or API‑like JSON from any public site.
Form automation: Fill out and submit complex web forms without manual coding.
Monitoring & change detection: Periodically visit pages, capture screenshots, and compare content.
Content analysis: Retrieve page text or DOM properties for downstream LLM reasoning.
Screenshot verification: Capture full‑page or viewport images for visual regression testing.

FAQ

Q: Which browsers are supported? A: Any Chrome or Chromium installation reachable from the host machine. The server launches Chrome in headless mode by default but can be configured via environment variables (e.g., DP_HEADLESS=0).

Q: Do I need a special Python version? A: Python 3.10+ is required; 3.11+ is recommended.

Q: How does the server handle authentication cookies or sessions? A: The server uses a regular Chrome profile, so any cookies or logged‑in sessions present in the profile are available to LLM commands. For security, use a dedicated profile when automating sensitive workflows.

Q: What if a selector fails? A: Tools return a clear error with the original selector and the normalized locator, allowing the LLM to adjust or retry quickly.

Q: Can I run the server inside a container? A: Yes, as long as Chrome/Chromium is installed in the container and the DISPLAY/headless settings are appropriately configured.

Q: How are errors reported to the LLM client? A: Responses follow the MCP tool contract, containing status, message, and optional data fields, all validated by Pydantic models.

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

Official Repositories: GitHub | GitCode

English Version | 中文版本

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

Unlike screenshot-based approaches, it provides structured, deterministic web automation through 19 tools plus MCP Resources/Prompts that leverage the efficiency of DrissionPage, a high-performance browser automation framework.

🌟 Why Choose DrissionPage MCP?

LLM-Optimized: Works with structured data instead of requiring vision models
Deterministic: Reliable element selection with CSS/XPath normalization for LLM-friendly selectors
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

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

🛠️ 19 Powerful Tools + MCP Resources/Prompts

page_navigate - Navigate to any URL
page_go_back / page_go_forward - Browser history
page_refresh - Reload current page

🎯 Element Interaction & Extraction (7 tools)

element_find - Find elements by CSS selector or XPath; bare selectors like h1 are treated as CSS
element_click - Click any element
element_type - Input text into elements
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

📸 Page Operations (5 tools)

page_screenshot - Capture full page or viewport
page_resize - Adjust browser window
page_click_xy - Click by coordinates
page_close - Close browser
page_get_url - Get current URL

⏱️ Wait Operations (3 tools)

wait_for_element - Wait for element to appear (with timeout)
wait_for_url - Wait until the current URL contains text
wait_time - Delay execution

🧩 MCP Resources and Prompts

Resources: drissionpage://session/summary, drissionpage://page/current, drissionpage://tools/catalog, drissionpage://policy/summary
Prompts: browser_navigate_and_summarize, browser_extract_structured_data, browser_fill_form_safely, 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
docs/release-checklist.md	Release validation and publishing checklist
examples/README.md	MCP client configuration examples
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/              # 19 automation tools
├── examples/               # Configuration templates
├── tests/                  # Unit tests
└── playground/             # Testing utilities

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"
# DP_NO_SANDBOX = "1"

You can also add it with the Codex CLI:

codex mcp add drissionpage -- drissionpage-mcp

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

See examples/README.md for more configuration options.

📋 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 75% floor and uploads coverage.xml)
python -m pytest tests/ --cov=drissionpage_mcp --cov-report=term-missing --cov-report=xml

GitHub Actions runs lint, unit, protocol, package, browser integration, and coverage jobs. Codecov is configured through codecov.yml and the CI workflow; set the CODECOV_TOKEN repository secret so the upload step can publish coverage.xml reliably from GitHub Actions.

Try It Out

# Interactive testing
python playground/local_test.py

# Quick start validation
python playground/quick_start.py

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

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	✅ Unit/protocol checks, optional browser smoke
Documentation	✅ Setup, compatibility, troubleshooting, release checklist
Package	✅ PyPI metadata and build checks
Status	🟡 Beta; real browser behavior depends on local Chrome/Chromium and target sites

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

🗺️ Roadmap

Current (v0.4.1)

19 core automation tools with removed alias surface
stdio MCP server integration
Doctor diagnostics for local setup
Stable JSON mirror, structuredContent, and typed per-tool MCP outputSchema
Opt-in local safety policy for navigation and screenshot paths
Resources, prompts, eval harness, compatibility, and troubleshooting documentation
PyPI distribution

Future (v0.5+)

📖 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"
    }
  }
}

Claude Desktop

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

See examples/ for more client configurations.

🤝 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

🙏 Acknowledgments

DrissionPage - Excellent browser automation library
Model Context Protocol - Protocol specification
Claude - Making AI assistants capable and useful

💬 Support

📖 Troubleshooting
🐛 Report Issues
💡 Feature Requests
🔗 GitHub Repository
📦 PyPI Package

📈 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.4.1

Released on 2026-06-26. This release focuses on MCP client reliability and the issues found during real Codex/LLM browser testing:

Fixed selector normalization: bare selectors such as h1 and input[name=q] are now treated as CSS before calling DrissionPage.
Preserved explicit DrissionPage locators such as tag:h1, text:Submit, xpath://h1, and @name=value.
Added selector metadata to tool responses so clients can see the original selector, normalized locator, strategy, and whether normalization happened.
Fixed MCP serverInfo.version to report the drissionpage-mcp package version instead of the MCP SDK version.
Renamed the public element_get_property input field from property_name to property with no compatibility alias.
Reduced element_find default timeout to 3 seconds for faster failed-selector feedback.
Made browser-backed CI jobs fail when Chromium is installed but browser integration cannot run.

DrissionPage MCP Server