DrissionPage MCP Server

DrissionPage MCP Server

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

Official Repositories: GitHub | GitCode

English Version | 中文版本

🧭 Client Setup Navigation

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

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.

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"

🛠️ 19 Powerful Tools + MCP Resources/Prompts

🌐 Navigation (4 tools)

• 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

🏗️ 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
├── 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"
      }
    }
  }
}

📋 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, andcoverage jobs. Codecov is configured through codecov.yml and the CI workflow;set the CODECOV_TOKEN repository secret so the upload step can publishcoverage.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

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+)

• Form handling utilities
• File upload support
• Shadow DOM selectors
• Session persistence
• 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). Youcan 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!

1. Fork the repository
2. Create a feature branch
3. Make focused changes
4. Run the relevant checks
5. 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.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.