drissionpage-mcp-browser-automation

# DrissionPage MCP Browser Automation > Skill by [ara.so](https://ara.so) — MCP Skills collection. DrissionPage MCP Server brings professional browser automation to Claude Code, Codex, Cursor, and other MCP clients. It provides 52 tools for deterministic web automation through the Model Context Protocol, leveraging DrissionPage's efficient engine for structured, LLM-optimized browser control. ## Installation ```bash # Install from PyPI python -m pip install -U drissionpage-mcp # Verify installation drissionpage-mcp --version drissionpage-mcp doctor ``` ## Configuration ### Codex CLI/IDE (Recommended) Add to `~/.codex/config.toml` or `.codex/config.toml` in your project: ```toml [mcp_servers.drissionpage] command = "drissionpage-mcp" startup_timeout_sec = 20 tool_timeout_sec = 60 # Optional environment variables [mcp_servers.drissionpage.env] # CHROME_PATH = "/custom/path/to/chrome" # DP_HEADLESS = "1" # DP_MCP_SCREENSHOT_ROOT = "/path/to/screenshots" # DP_MCP_UPLOAD_ROOT = "/path/to/uploads" ``` Or via CLI: ```bash codex mcp add drissionpage -- drissionpage-mcp ``` ### Claude Desktop / Cursor Add to MCP settings JSON (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "drissionpage": { "command": "drissionpage-mcp" } } } ``` For GUI-launched clients that don't inherit shell PATH: ```json { "mcpServers": { "drissionpage": { "command": "/absolute/path/to/python", "args": ["-m", "drissionpage_mcp.cli"] } } } ``` ### Environment Variables - `CHROME_PATH` - Custom Chrome/Chromium executable path - `DP_HEADLESS` - Set to `"1"` for headless mode - `DP_MCP_SCREENSHOT_ROOT` - Directory for saved screenshots - `DP_MCP_UPLOAD_ROOT` - Directory for file uploads (security boundary) - `LOG_LEVEL` - Logging level (DEBUG, INFO, WARNING, ERROR) ## Core Tool Categories ### Navigation Tools **page_navigate** - Navigate to URLs with optional tab control: ```python # Basic navigation page_navigate(url="https://example.com") # Open in new tab page_navigate(url="https://github.com", new_tab=True) # Navigate and get page summary page_navigate(url="https://news.ycombinator.com", observe=True) ``` **page_go_back / page_go_forward** - Browser history navigation: ```python page_go_back() page_go_forward() ``` **page_refresh** - Reload current page: ```python page_refresh() ``` ### Element Discovery & Interaction **element_find** - Find single elements (CSS or XPath): ```python # CSS selector (default) element_find(selector="button.submit") # XPath element_find(selector="//button[@type='submit']") # Get element details result = element_find(selector="input[name='username']") # Returns: tag, text, attributes, recommended_selector ``` **element_find_all** - Extract multiple elements: ```python # Find all article links element_find_all( selector="article h2 a", limit=10 ) # Returns bounded list with text, href, and recommended selectors ``` **element_click** - Click elements: ```python # Click by CSS selector element_click(selector="button#submit") # Click with scroll into view element_click(selector=".modal-close", scroll_into_view=True) ``` **element_type** - Input text: ```python # Type into input field element_type(selector="input[name='email']", text="user@example.com") # Clear and type element_type(selector="#search", text="Python tutorials", clear=True) ``` **element_upload_file** - Upload files: ```python # Upload file (must be under DP_MCP_UPLOAD_ROOT) element_upload_file( selector="input[type='file']", file_path="document.pdf" ) ``` **element_select** - Handle dropdowns: ```python # Select by visible text element_select(selector="select[name='country']", value="United States") # Select by index element_select(selector="select#size", index=2) ``` **element_check** - Toggle checkboxes/radios: ```python # Check a checkbox element_check(selector="input#agree-terms", check=True) # Uncheck element_check(selector="input[name='newsletter']", check=False) ``` ### Data Extraction **element_get_text** - Extract text content: ```python # Get element text element_get_text(selector="article .content") # Get all page text element_get_text() ``` **element_get_attribute** - Get HTML attributes: ```python # Get href attribute element_get_attribute(selector="a.download", attribute="href") # Get data attribute element_get_attribute(selector="div.widget", attribute="data-id") ``` **element_get_property** - Get DOM properties: ```python # Get input value element_get_property(selector="input#username", property="value") # Check if checkbox is checked element_get_property(selector="input[type='checkbox']", property="checked") ``` **element_get_html** - Get HTML content: ```python # Get element HTML element_get_html(selector="div.article") # Get entire page HTML element_get_html() ``` ### Page Understanding **page_snapshot** - Get structured page overview: ```python page_snapshot() # Returns: headings, links, buttons, inputs, forms with recommended selectors ``` **page_observe** - Get page fingerprint: ```python page_observe() # Returns: URL, title, element counts, visible text samples, active element, console summary ``` **form_inspect** - Analyze forms: ```python form_inspect(selector="form#checkout") # Returns: action, method, controls with labels, types, requirements, options ``` ### Screenshots & Visual **page_screenshot** - Capture inline screenshot: ```python # Full page screenshot (base64) page_screenshot(full_page=True) # Viewport only page_screenshot(full_page=False) ``` **page_screenshot_save** - Save screenshot to disk: ```python # Save with auto-generated filename page_screenshot_save(full_page=True) # Custom filename (saved under DP_MCP_SCREENSHOT_ROOT) page_screenshot_save(filename="homepage.png", full_page=True) ``` ### Tab Management **tab_list** - List open tabs: ```python tab_list() # Returns: list of tabs with MCP tab IDs, titles, URLs ``` **tab_switch** - Switch to tab: ```python # Switch using tab_id from tab_list tab_switch(tab_id="tab_0") ``` **tab_close** - Close tab: ```python # Close specific tab tab_close(tab_id="tab_1") ``` ### Frame & Shadow DOM **frame_list** - List iframes: ```python frame_list() # Returns: iframe details without changing frame context ``` **frame_snapshot** - Inspect iframe content: ```python frame_snapshot(selector="iframe#payment-form") # Returns: bounded outline of iframe content ``` **frame_find** - Find element in iframe: ```python frame_find( frame_selector="iframe#widget", selector="button.submit" ) ``` **shadow_find** - Find in shadow DOM: ```python shadow_find( host_selector="custom-element", selector=".internal-button" ) ``` **shadow_find_all** - Extract from shadow DOM: ```python shadow_find_all( host_selector="product-list", selector=".item", limit=10 ) ``` ### Wait Operations **wait_for_element** - Wait for element to appear: ```python wait_for_element(selector="div.results", timeout=10) ``` **wait_for_url** - Wait for URL change: ```python wait_for_url(text="confirmation", timeout=15) ``` **wait_until** - Wait for conditions: ```python # Wait until element is clickable wait_until( selector="button.submit", condition="clickable", timeout=10 ) # Available conditions: clickable, hidden, visible, stable, text_match, url_contains ``` **wait_time** - Simple delay: ```python wait_time(seconds=2) ``` ### Cookies & Storage **browser_cookies_get** - Read cookies: ```python # Get all cookies (values redacted by default) browser_cookies_get() # Get specific cookie with value browser_cookies_get(name="session_id", show_value=True) ``` **storage_get** - Read localStorage/sessionStorage: ```python # Get specific key storage_get(storage_type="local", key="user_preferences") # Get all storage as map storage_get(storage_type="session") ``` **storage_set** - Set storage value: ```python storage_set( storage_type="local", key="theme", value="dark" ) ``` **storage_clear** - Clear storage: ```python # Clear specific key storage_clear(storage_type="local", key="cache") # Clear all localStorage storage_clear(storage_type="local") ``` ### JavaScript Execution **page_evaluate** - Run JavaScript: ```python # Execute JS and get result page_evaluate(script="return document.title") # Complex JS with bounded result page_evaluate(script=""" return Array.from(document.querySelectorAll('a')) .slice(0, 10) .map(a => ({ text: a.textContent, href: a.href })) """) ``` ### Page Actions **page_scroll** - Scroll page: ```python # Scroll down page_scroll(direction="down", amount=500) # Scroll to specific position page_scroll(y=1000) ``` **keyboard_press** - Send keyboard input: ```python # Press Enter keyboard_press(key="Enter") # Press Escape keyboard_press(key="Escape") ``` **page_click_xy** - Click by coordinates: ```python page_click_xy(x=100, y=200) ``` **page_resize** - Resize browser window: ```python page_resize(width=1920, height=1080) ``` ### Debug & Diagnostics