DrissionPage BetterMCP

A better DrissionPage MCP server — covers most capabilities of the original library, 255 unit tests, 100% service coverage, AI-optimized tool calls and descriptions.

English | 中文

---

Why BetterMCP

	BetterMCP	Note
55 Tools	Covers browser, tabs, navigation, elements, forms, screenshots, network, cookies, storage, iframes, files, and more	Most capabilities of the original library, ready out of the box
255 Unit Tests	17 test modules + 6 integration test suites	100% service coverage, verifiable on every commit
AI-Friendly	Clear tool descriptions, explicit parameter semantics, unified response structure	LLMs understand on first call — fewer retries, less token waste
Element Cache	element_find returns an element_id for direct reuse in subsequent calls	No repeated lookups, more efficient interactions
Native Locator Syntax	#id .class @attr text: css: xpath: @@AND @|OR	Full DrissionPage syntax support
Dual Transport	stdio + streamable-http	Works with all major AI coding tools

Quick Start

Prerequisites

• Python >= 3.10
• uv
• Chrome / Chromium browser

Install

git clone https://github.com/pureTrue/DrissionPage-BetterMCP.git
cd DrissionPage-BetterMCP
uv sync

Configure Your AI Tool

<!-- tabs:start -->

Claude Code

Project root .mcp.json:

{
  "mcpServers": {
    "drissionpage": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/DrissionPage-BetterMCP", "dp-mcp"]
    }
  }
}

Or via CLI:

claude mcp add drissionpage -- uv run --directory /path/to/DrissionPage-BetterMCP dp-mcp

Cursor

.cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "drissionpage": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/DrissionPage-BetterMCP", "dp-mcp"]
    }
  }
}

VS Code (Copilot)

.vscode/mcp.json:

{
  "servers": {
    "drissionpage": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/DrissionPage-BetterMCP", "dp-mcp"]
    }
  }
}

Note: VS Code uses servers as the top-level key, not mcpServers.

Codex

.codex/config.toml (project-level) or ~/.codex/config.toml (global):

[mcp_servers.drissionpage]
command = "uv"
args = ["run", "--directory", "/path/to/DrissionPage-BetterMCP", "dp-mcp"]

Or via CLI:

codex mcp add drissionpage -- uv run --directory /path/to/DrissionPage-BetterMCP dp-mcp

<!-- tabs:end -->

Replace /path/to/DrissionPage-BetterMCP with the actual project path.

Environment Variables

Optional, prefixed with DP_MCP_:

Variable	Default	Description
DP_MCP_DEFAULT_TIMEOUT	15.0	Default tool timeout (seconds)
DP_MCP_LOG_LEVEL	INFO	Logging level
DP_MCP_NETWORK_CAPTURE_SIZE	200	Max network packets to capture

Copy .env.example to .env and customize as needed.

Tool List

Browser Management

Tool	Description
browser_connect	Connect to an existing Chrome or launch a new instance; supports headless, proxy, user_agent
browser_info	Get browser status: address, tab count, process ID
browser_quit	Close the browser and release all resources

Tab Management

Tool	Description
tab_new	Open a new tab, optionally navigate to a URL
tab_close	Close a tab; defaults to the current tab
tab_switch	Switch to a specific tab
tab_list	List all open tabs
tab_find	Search tabs by title and/or URL
tab_info	Get tab details

Page Navigation

Tool	Description
page_navigate	Navigate to a URL; returns final URL and page title
page_back / page_forward	Go back or forward in history
page_refresh	Refresh the page; optionally ignore cache
page_stop	Stop page loading

Element Interaction

Tool	Description
element_find	Find an element; returns a cached element_id
element_find_all	Find all matching elements
element_wait	Wait for an element state (present / visible / hidden / deleted)
element_click	Click an element; supports left / right / middle / double click
element_input	Type text into an input; optionally clear first
element_clear	Clear an input field
element_hover	Hover over an element
element_drag	Drag to a target element or pixel offset
element_get_text	Get visible text content
element_get_attr	Get an HTML attribute value
element_get_info	Get full details: tag, text, rect, attrs, HTML, states
element_select	Select an option in a <select> element
element_get_options	Get all options of a <select> element
element_scroll_into_view	Scroll until the element is visible

Screenshots

Tool	Description
page_screenshot	Screenshot the page; supports full-page capture
element_screenshot	Screenshot a specific element

Page Content

Tool	Description
page_get_text	Get the page's plain text
page_get_html	Get the HTML source
page_wait_load	Wait for page load / URL change / title change
page_scroll	Scroll the page in a direction

Iframes

Tool	Description
frame_list	List all iframes
frame_switch	Switch into an iframe
frame_parent	Return to the parent frame
frame_main	Return to the top-level page

Network Capture

Tool	Description
network_listen_start	Start listening for requests matching a URL pattern
network_listen_wait	Wait for and retrieve captured network packets

Cookies & Storage

Tool	Description
cookie_get_all	Get all cookies; optionally filter by domain
cookie_set	Set a cookie
cookie_remove	Remove a cookie or clear all
storage_get	Read from localStorage / sessionStorage
storage_set	Write to localStorage / sessionStorage

Keyboard & Dialogs

Tool	Description
keyboard_press	Press a key or combination (Enter, Ctrl+A, etc.)
keyboard_type	Type text continuously
dialog_handle	Handle an alert / confirm / prompt dialog
dialog_auto	Enable or disable automatic dialog handling

Advanced

Tool	Description
action_chain	Execute an action sequence: move, click, drag, type, wait
js_execute	Execute JavaScript on the page
cdp_execute	Execute a raw Chrome DevTools Protocol command

File Operations

Tool	Description
file_upload	Upload a file; supports hidden inputs
file_download	Download a file via URL or click trigger
page_save	Save the page as PDF or MHTML

Developer Guide

Project Structure

src/dp_mcp/
├── server.py              # MCP server — 55 tool definitions
├── config.py              # Settings (pydantic-settings)
├── models.py              # ToolResult, BrowserInfo, TabInfo, etc.
├── core/                  # Core services
│   ├── browser.py         # Browser lifecycle
│   ├── tab.py             # Multi-tab management
│   ├── navigation.py      # Page navigation
│   └── element.py         # Element finding & interaction
├── services/              # Domain services
│   ├── screenshot.py      # Screenshots
│   ├── frame.py           # Iframes
│   ├── scroll.py          # Scrolling
│   ├── network.py         # Network capture
│   ├── cookie.py          # Cookies
│   ├── action.py          # Action chains
│   ├── dialog.py          # Dialogs
│   ├── cdp.py             # CDP
│   └── file.py            # File operations
└── utils/
    └── locator.py         # Locator parser + element cache

Running Tests

# Unit tests (no browser needed)
uv run pytest tests/unit -v

# Integration tests (requires Chrome)
uv run pytest tests/integration -v -m integration

# All tests
uv run pytest -v

Locator Syntax

Full DrissionPage locator syntax is supported:

Syntax	Example	Description
#id	#login-btn	By ID
.class	.submit	By class name
@attr=val	@name=email	By attribute
text:str	text:Login	By visible text
tag:name	tag:input	By tag name
css:selector	css:div.card>h2	CSS selector
xpath:expr	xpath://div[@id='app']	XPath
@@a@@b	@@class=btn@@text()=OK	AND condition
@|a@|b	@|class=btn@|class=link	OR condition

Use the optional by parameter to disambiguate: css, xpath, text, id, class, attr.

Contributing

Pull requests and issues are welcome.

1. Fork this repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Commit your changes: git commit -m "feat: add my feature"
4. Push the branch: git push origin feature/my-feature
5. Open a Pull Request

Please make sure all tests pass before submitting:

uv run pytest tests/unit -v

License

This project's code is licensed under BSD 3-Clause.

Note: This project depends on DrissionPage, which uses a custom non-commercial license that prohibits unauthorized commercial use. Users must independently comply with DrissionPage's license terms.