drissionpage-mcp 0.5.0

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

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

---

🛠️ 22 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 (8 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_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 (6 tools)

• page_screenshot - Capture full page or viewport
• page_snapshot - Return a bounded page outline with headings, links, buttons, inputs, forms, and selector recommendations
• 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
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/              # 22 automation and page-understanding 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

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",
        "DP_NO_SANDBOX": "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

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

---

🗺️ Roadmap

Current (v0.5.0)

• 22 core automation, page-understanding, and form-inspection 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
• 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). 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!

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

Released on 2026-06-29. This release starts the 0.5 form workflow with a safe read-only inspection tool while preserving the 0.4 recovery improvements:

• form_inspect inspects forms and controls with labels, selectors, methods/actions, required/disabled/read-only state, select options, and opt-in non-password values.
• Failure payloads include machine-readable error.details.hints for common recovery paths.
• Missing element and selector failures suggest page_snapshot, element_find_all, wait_for_element, and iframe/dynamic-content checks.
• page_snapshot now keeps inputs, buttons, and forms visible on link-heavy pages while respecting the total max_elements cap.
• Timeout, browser startup, screenshot, navigation, policy, invalid-argument, and unknown-tool failures now include targeted next steps.
• MCP_ARGUMENT_INVALID still protects strict schemas and now points clients toward exact snake_case field names.
• Browser startup hints point to drissionpage-mcp doctor --launch-browser, CHROME_PATH, DP_HEADLESS, and DP_NO_SANDBOX.
• The top-level JSON_RESULT envelope, strict input schemas, and typed outputSchema contracts remain unchanged; the public registry now has 22 tools.