Skip to content
Back to search

Drissionpage-MCP-Server

DrissionPage MCP Server · Browser automation for Claude Code, Codex, and MCP clients

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jumodada--drissionpage-mcp-server/badge.svg)](/listings/jumodada--drissionpage-mcp-server)

HTML

<a href="/listings/jumodada--drissionpage-mcp-server"><img src="/api/listings/jumodada--drissionpage-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

<p align="center"> </p>

For Claude Code, Claude Desktop, and other JSON-based MCP clients, see [Integration Examples](#-integration-examples).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 717 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # DrissionPage MCP Server
  2. > Professional browser automation for Codex, Claude Code, and MCP clients, powered by [DrissionPage](https://github.com/g1879/DrissionPage).
  3. >
  4. > DrissionPage is a Python web automation library built around direct Chromium/CDP control with requests-style HTTP session support. This server exposes its browser-facing capabilities as typed, atomic MCP tools.
  5. [![PyPI](https://img.shields.io/pypi/v/drissionpage-mcp.svg?cacheSeconds=3600)](https://pypi.org/project/drissionpage-mcp/) [![Downloads](https://pepy.tech/badge/drissionpage-mcp/month)](https://pepy.tech/project/drissionpage-mcp) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![CI](https://github.com/jumodada/Drissionpage-MCP-Server/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jumodada/Drissionpage-MCP-Server/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/jumodada/Drissionpage-MCP-Server/branch/main/graph/badge.svg)](https://codecov.io/gh/jumodada/Drissionpage-MCP-Server) [![Status](https://img.shields.io/badge/status-beta-yellow.svg)]()
  6. [![DrissionPage MCP interactive Browser Lab](https://raw.githubusercontent.com/jumodada/Drissionpage-MCP-Server/assets/drissionpage-mcp-browser-lab.gif)](https://drissionpage-mcp.vercel.app)
  7. **[Open the interactive Browser Lab](https://drissionpage-mcp.vercel.app)** to replay bounded natural pointer motion, drag controls, and verify observable state.
  8. **Official Repositories**: [GitHub](https://github.com/jumodada/Drissionpage-MCP-Server) | [GitCode](https://gitcode.com/g1879/DrissionMCP)
  9. [English Version](README.md) | [中文版本](README_CN.md)
  10. ## 🖱️ Atomic Browser Control with Natural Pointer Motion
  11. **DrissionPage MCP 0.9.0 exposes 69 typed browser capabilities.** The MCP server provides accurate low-level observation and interaction; the client or an optional Skill composes those capabilities for a site, component library, challenge, or business workflow.
  12. <!-- mcp-name: io.github.jumodada/drissionpage-mcp -->
  13. > **The model decides what to do; the MCP executes the requested browser operation exactly.**
  14. ```text
  15. Screenshot / page observation
  16. ↓
  17. Multimodal model identifies viewport coordinates
  18. ↓
  19. page_click_xy(x=442, y=369, profile="natural")
  20. ↓
  21. 24-step eased cubic path → exact target → press → release
  22. ↓
  23. Observe and verify the resulting page state
  24. ```
  25. ### Core interaction guarantees
  26. - **Two bounded profiles**: `direct` emits one exact move; `natural` emits a deterministic 24-step eased cubic path with reproducible 8-14ms intervals and exact final arrival.
  27. - **No hidden randomness**: the same start, target, and profile produce the same path; there is no jitter, overshoot, or anti-detection logic. Pointer position is stateful, so a repeated call can begin from the previous endpoint.
  28. - **Explicit sequences**: click is the selected move profile, optional caller-specified delay, press, release; drag keeps one press across the selected path and ordered waypoints.
  29. - **Failure-safe input**: a pressed pointer button is released if execution fails after the press.
  30. - **Fresh browser evidence**: selector geometry is resolved immediately before selector-backed drag operations.
  31. - **Typed results**: outputs report the executed coordinates, button, step count, and explicit delay metadata.
  32. Use structured DOM targets when reliable selectors exist. Use coordinates, `natural` motion, and explicit drag waypoints for canvas controls, editors, maps, charts, and other visual-only surfaces. Component-specific target discovery, challenge observation, multi-click sequencing, login procedures, and other business policy belong in the client or an optional Skill.
  33. ```json
  34. {
  35. "x": 442,
  36. "y": 369,
  37. "profile": "natural",
  38. "button": "left",
  39. "element": "visually identified control"
  40. }
  41. ```
  42. Designed for authorized browser automation, testing, accessibility workflows, and technical research. The core does not provide challenge-specific or site-specific workflows.
  43. ## 🧭 Client Setup Navigation
  44. - [Atomic browser control](#-atomic-browser-control-with-natural-pointer-motion)
  45. - [Install + screenshot walkthrough](#-first-success-path)
  46. - [Codex CLI/IDE quick setup](#-setup-in-codex-cliide-30-seconds)
  47. - [Codex CLI/IDE integration example](#codex-cli--ide)
  48. - [Skills and reusable procedures](#-skills-and-reusable-procedures)
  49. - [Claude Code setup](#claude-code)
  50. - [Cursor setup](#cursor)
  51. - [Claude Desktop setup](#claude-desktop)
  52. - [Troubleshooting](#-troubleshooting)
  53. ---
  54. ## 🚀 What is DrissionPage MCP?
  55. **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.
  56. The standalone server exposes 69 typed tools, zero MCP prompts, and one static optional-Skills catalog resource. Version 0.9.0 keeps that registry stable while tightening opt-in navigation policy matching and rejecting denied destinations before browser startup. Every tool loads by default; there is no capability profile or opt-in `full` mode. Models compose these atomic capabilities, while reusable challenge and site procedures live outside the distribution as optional Skills. Browser execution is powered by [DrissionPage](https://github.com/g1879/DrissionPage).
  57. ### 🌟 Why Choose DrissionPage MCP?
  58. - **Structured-First, Vision-Ready**: Uses DOM structure when available and multimodal coordinates when visual interaction is the better tool
  59. - **Deterministic**: Reliable element selection with CSS/XPath normalization for LLM-friendly selectors
  60. - **Natural Pointer Motion**: Offers exact direct movement and a bounded deterministic 24-step eased trajectory from the same atomic tools
  61. - **Fast & Lightweight**: Built on DrissionPage's efficient engine with minimal overhead
  62. - **Type-Safe**: Full type hints and Pydantic validation for all tools
  63. - **Open-source Friendly**: Includes compatibility notes, troubleshooting, and CI checks for maintainable contributions
  64. - **Easy Integration**: Simple `pip install` + Codex TOML or MCP JSON configuration
  65. ### ✅ Quality and Real-World Validation
  66. DrissionPage MCP is backed by a strict regression suite and browser-backed scenario checks:
  67. - **Strict automated tests**: unit, protocol, schema snapshot, response-contract, resource, release-metadata, security-policy, browser-integration, and coverage checks run in CI.
  68. - **95% coverage floor**: CI enforces the current 95% coverage threshold and uploads coverage reports.
  69. - **Real browser verification**: Chrome/Chromium-backed integration tests exercise the same MCP tools exposed to clients.
  70. - **Document-boundary verification**: focused browser tests prove cross-origin OOPIF reads and DrissionPage-exposed closed Shadow DOM lookup without JavaScript piercing fallbacks.
  71. - **Challenge-surface verification**: local fixtures cover normal, hidden, off-viewport, delayed, and CSS 3D cross-origin widgets; official Turnstile dummy keys cover visible, invisible, pass, fail, and forced-interactive callbacks without retaining tokens.
  72. - **Scenario validation**: the playground MCP Lab covers realistic forms, commerce pages, social feeds, timelines, dynamic waits, iframe cases, and recovery paths without depending on public demo websites.
  73. ---
  74. ## ⚡ First Success Path
  75. 0.9.0 is currently a local candidate. Until it is published, validate it from a
  76. source checkout with `python -m pip install -e .` or install a locally built wheel.
  77. The PyPI version command below applies after publication.
  78. ```bash
  79. # Install or update Codex CLI (macOS/Linux)
  80. curl -fsSL https://chatgpt.com/codex/install.sh | sh
  81. # Install from PyPI
  82. python -m pip install -U "drissionpage-mcp>=0.9.0"
  83. # Verify package and environment
  84. drissionpage-mcp --version
  85. drissionpage-mcp doctor
  86. ```
  87. The official installer updates an existing Codex CLI installation as well. For
  88. Windows and the Codex desktop app, see the [official Codex CLI and app
  89. documentation](https://developers.openai.com/codex/cli/).
  90. Then add the Codex or MCP client configuration below and restart your client.
  91. <p align="center">
  92. <img src="https://raw.githubusercontent.com/jumodada/Drissionpage-MCP-Server/assets/01-install.png" width="700" alt="pip install drissionpage-mcp">
  93. <br><br>
  94. <img src="https://raw.githubusercontent.com/jumodada/Drissionpage-MCP-Server/assets/03-doctor.png" width="700" alt="drissionpage-mcp doctor — all checks green">
  95. </p>
  96. ---
  97. ## 📦 Setup in Codex CLI/IDE (30 seconds)
  98. Codex supports local stdio MCP servers through `config.toml`; the CLI and IDE extension share the same MCP configuration.
  99. 1. **Edit Codex configuration**:
  100. - User-level: `~/.codex/config.toml`
  101. - Project-level: `.codex/config.toml` inside a trusted project
  102. 2. **Add this configuration**:
  103. ```toml
  104. [mcp_servers.drissionpage]
  105. command = "drissionpage-mcp"
  106. startup_timeout_sec = 20
  107. tool_timeout_sec = 60
  108. ```
  109. 3. **Restart Codex**. In the TUI, run `/mcp`; from a shell, run `codex mcp list`.
  110. <p align="center">
  111. <img src="https://raw.githubusercontent.com/jumodada/Drissionpage-MCP-Server/assets/06-codex.png" width="700" alt="Codex config.toml">
  112. </p>
  113. For Claude Code, Claude Desktop, and other JSON-based MCP clients, see [Integration Examples](#-integration-examples).
  114. ---
  115. ## 🎯 Quick Examples
  116. ### Navigate and Screenshot
  117. ```
  118. "Visit https://example.com and take a screenshot for me"
  119. ```
  120. ### Search and Extract
  121. ```
  122. "Go to Wikipedia, search for Python, and get the first paragraph"
  123. ```
  124. ### Form Automation
  125. ```
  126. "Fill out the form at https://httpbin.org/forms/post and submit it"
  127. ```
  128. ### Data Scraping
  129. ```
  130. "Get the top 10 news headlines from news.ycombinator.com"
  131. ```
  132. ---
  133. ## 🛠️ 69 Typed Browser Tools
  134. All 63 tab-scoped tools accept an optional `tab_id`. Omit it to capture the MCP
  135. current tab once at call start, or pass an MCP/native DrissionPage tab id to
  136. target explicitly. Successful tab-scoped results return the resolved MCP
  137. `tab_id`; independent tabs can run concurrently while actions on one tab remain
  138. serialized.
  139. ### 🌐 Navigation (5 tools)
  140. - `page_navigate` - Navigate to any URL; target an existing `tab_id`, or combine `new_tab=true` with optional `background`, `new_window`, or `new_context`; `observe` returns a change summary
  141. - `page_navigate_with_http_auth` - Navigate through a scoped HTTP auth challenge in a dedicated disposable Chromium context without returning credentials
  142. - `page_go_back` - Navigate backward in browser history
  143. - `page_go_forward` - Navigate forward in browser history
  144. - `page_refresh` - Reload current page
  145. ### 🗂️ Tab Operations (3 tools)
  146. - `tab_list` - List open browser tabs with stable MCP tab IDs
  147. - `tab_switch` - Switch to a tab returned by `tab_list`
  148. - `tab_close` - Reject new work, drain in-flight actions, then close one tab without closing the whole browser
  149. ### 🎯 Element Interaction & Extraction (16 tools)
  150. - `element_find` - Find one element by CSS selector or XPath; bare selectors like `h1` are treated as CSS
  151. - `element_find_all` - Extract bounded repeated elements with text, attributes, and recommended selectors
  152. - `element_click` - Click any element with additive left/right/middle and single/double-click semantics
  153. - `element_click_and_download` - Correlate one selector, coordinate, or keyboard trigger with one integrity-checked artifact under `DP_MCP_DOWNLOAD_ROOT`
  154. - `element_type` - Input text into elements
  155. - `element_upload_file` - Use `element_upload_file(paths=[...])` to upload files from `DP_MCP_UPLOAD_ROOT` to `input[type=file]`
  156. - `element_click_and_upload` - Arm Chromium's file chooser, click its trigger, inject approved files, and clean interception without an operating-system picker
  157. - `element_scroll_into_view` - Bring an element into the viewport before acting
  158. - `element_hover` - Hover an element to trigger menu/tooltip states
  159. - `element_select` - Select an option by value, text, or index
  160. - `element_check` - Check or uncheck checkbox/radio controls
  161. - `element_get_text` - Get element or page text
  162. - `element_get_attribute` - Get an HTML attribute
  163. - `element_get_property` - Get a live DOM property such as an input value
  164. - `element_get_html` - Get element or page HTML
  165. - `element_state_get` - Read live DrissionPage state flags and document/viewport geometry for one element
  166. ### 📸 Page Operations (18 tools)
  167. - `page_screenshot` - Capture an inline full-page or viewport screenshot
  168. - `page_screenshot_save` - Save a screenshot under `DP_MCP_SCREENSHOT_ROOT`
  169. - `page_export_artifact` - Generate a managed PDF or MHTML artifact under `DP_MCP_ARTIFACT_ROOT` with SHA-256 and receipt evidence
  170. - `page_snapshot` - Return a bounded page outline with headings, links, buttons, inputs, forms, and selector recommendations
  171. - `page_accessibility_snapshot` - Return a bounded Chromium accessibility tree for the page or a scoped element, with field values redacted unless explicitly requested
  172. - `page_observe` - Return a compact page fingerprint with URL, title, counts, visible text samples, active element, and recent console summary
  173. - `page_evaluate` - Run bounded JavaScript in the current page and return a JSON-safe result
  174. - `page_scroll` - Use `page_scroll(pixels=...)` for relative scrolling, or pass `x`/`y` for an absolute position
  175. - `keyboard_press` - Send keys to the active element/page without echoing the input in results
  176. - `page_resize` - Adjust browser window
  177. - `page_pointer_move` - Move to exact viewport CSS coordinates with `direct` or bounded deterministic `natural` motion
  178. - `page_pointer_drag` - Perform one failure-safe coordinate drag through up to six optional ordered waypoints with the selected profile
  179. - `page_pointer_drag_element` - Resolve source and destination geometry immediately before dragging; supports CSS/XPath in the top document or one same-origin iframe, plus CSS paths through nested open Shadow DOM hosts
  180. - `page_click_xy` - Move with `direct` or `natural` motion, optionally wait for an explicit delay, then press and release at the exact target
  181. - `page_close` - Close browser
  182. - `page_get_url` - Get current URL
  183. - `page_dialog_observe` - Wait for and inspect a pending native alert, confirm, or prompt without handling it
  184. - `page_dialog_respond` - Use `page_dialog_respond(action="accept")` (or `"dismiss"`) for one pending alert, confirm, or prompt
  185. ### 🧱 Frame / Shadow DOM (5 tools)
  186. - `frame_list` - List iframe/frame contexts without changing global frame state
  187. - `frame_snapshot` - Use `frame_snapshot(frame_selector="...")` or `frame_index` to inspect one iframe with bounded outline data
  188. - `frame_find` - Find an element inside a selected iframe
  189. - `shadow_find` - Find one element inside a shadow root exposed by the current supported DrissionPage runtime, including tested closed roots
  190. - `shadow_find_all` - Extract repeated elements from a DrissionPage-exposed shadow root
  191. ### 🌍 Browser Environment (6 tools)
  192. - `browser_headers_set` - Replace extra request headers and return names with redacted values; an empty object clears them
  193. - `browser_user_agent_set` - Override the user agent and optional platform, returning both the accepted and previous user agents
  194. - `browser_cache_clear` - Clear HTTP cache while preserving Cookies, localStorage, and sessionStorage
  195. - `browser_permission_get` - Query one browser permission for the current document origin without opening an OS prompt
  196. - `browser_permission_set` - Use `browser_permission_set(setting="granted")` (or `"denied"`/`"prompt"`) for an exact origin/current Chromium context
  197. - `browser_permissions_reset` - Reset permission overrides for the current Chromium context
  198. ### 🍪 Cookies & Storage (7 tools)
  199. - `browser_cookies_get` - Read normalized cookies with values redacted by default
  200. - `browser_cookies_set` - Set up to 100 cookies in one call and return accepted metadata with redacted values
  201. - `browser_cookies_delete` - Delete one named cookie with optional URL/domain/path scope
  202. - `browser_cookies_clear` - Clear all browser cookies
  203. - `storage_get` - Read localStorage/sessionStorage by key or as a map, with values redacted unless `include_values=true`
  204. - `storage_set` - Set one localStorage/sessionStorage item without echoing the value
  205. - `storage_clear` - Clear one storage key or an entire storage area
  206. ### 🧪 Debug / Observability (1 tool)
  207. - `page_console_logs` - Read bounded browser console messages with level filtering, cursor pagination, and limits
  208. ### ⏱️ Wait Operations (4 tools)
  209. - `wait_for_element` - Wait for element to appear (with timeout)
  210. - `wait_for_url` - Use `wait_for_url(url_pattern="...")` until the current URL contains the supplied text
  211. - `wait_until` - Use `wait_until(condition="text_contains", value="...")` or another documented condition/value pair
  212. - `wait_time` - Delay execution
  213. ### 🌐 Network Control & Observation (4 tools)
  214. - `network_listen_start` - Start bounded HTTP/XHR/Fetch observation through DrissionPage
  215. - `network_listen_wait` - Wait for bounded packet metadata with optional redacted headers or body excerpts
  216. - `network_listen_stop` - Stop observation and optionally clear queued packets
  217. - `network_blocked_urls_set` - Use `network_blocked_urls_set(urls=[...])` to replace blocked URL patterns; an empty list clears them
  218. ### 🧩 Optional Skills Discovery
  219. - Resource: `drissionpage://skills/catalog`
  220. - Prompts: none
  221. - Repository examples: `cross-origin-iframe-probe`, `turnstile-testing`, and `xiaohongshu-content-research`
  222. - Entry point: `skills/<skill-name>/SKILL.md`; catalog schema v2 includes Skill/MCP versions, required tools, fixture, fixed `v0.8.4` source revision, verification status, and SHA-256
  223. - Skills are Markdown procedures for the MCP host. They are not Python modules, are not executed by the server, and are excluded from wheel/sdist packages.
  224. Validate a source checkout with `python playground/validate_skills.py --json`.
  225. Install the fixed catalog release from
  226. [`skills-manager@v0.8.4`](https://github.com/jumodada/skills-manager/tree/v0.8.4)
  227. with `python install.py install --client codex --json` or
  228. `python install.py install --client claude --json`.
  229. ### 📖 Skills and Reusable Procedures
  230. The MCP core exposes atomic browser operations. Skills provide reusable,
  231. reviewable procedures outside the server:
  232. | Example Skill | What it demonstrates | Stop boundary |
  233. | --- | --- | --- |
  234. | [`cross-origin-iframe-probe`](skills/cross-origin-iframe-probe/SKILL.md) | Frame discovery, cross-origin diagnosis, coordinate fallback, and outside verification | Cannot read the inner DOM of a cross-origin iframe |
  235. | [`turnstile-testing`](skills/turnstile-testing/SKILL.md) | Cloudflare test fixtures, authorized production challenge interaction, coordinate geometry, and parent-page checks | Use the documented support matrix and verify the resulting page state |
  236. | [`xiaohongshu-content-research`](skills/xiaohongshu-content-research/SKILL.md) | Bounded read-only note research and the deterministic `social-notes` fixture | Stop on robots, login, captcha, safety page, or rate limit |
  237. Read the full [Skills guide](docs/skills.md) before publishing a new procedure.
  238. Skills must use existing typed tools, collect fresh evidence, verify
  239. postconditions, redact secrets, and state unsupported cases. They do not add
  240. new MCP tools or override the server's navigation and safety policy. Multi-tab
  241. Skills should carry the returned MCP `tab_id` into later tab-scoped calls rather
  242. than relying on mutable current-tab state.
  243. ---
  244. ## 📚 Documentation
  245. | Guide | Description |
  246. |-------|-------------|
  247. | [README.md](README.md) | Installation, tools, and architecture |
  248. | [docs/compatibility.md](docs/compatibility.md) | Supported Python, DrissionPage, MCP, and browser versions |
  249. | [docs/tool-contract.md](docs/tool-contract.md) | Public MCP tool names, inputs, annotations, and response shape |
  250. | [docs/troubleshooting.md](docs/troubleshooting.md) | Doctor command, browser startup, and client setup fixes |
  251. | [CHANGELOG.md](CHANGELOG.md) | Release notes |
  252. ---
  253. ## 🏗️ Architecture
  254. Built with **clean, modular design**:
  255. ```
  256. DrissionMCP/
  257. ├── drissionpage_mcp/
  258. │ ├── cli.py # Process entry point
  259. │ ├── server.py # MCP transport and request routing
  260. │ ├── context.py # Browser and tab lifecycle facade
  261. │ ├── runtime.py # Operation keys, receipts, artifacts, and capability state
  262. │ ├── tool_outputs.py # Typed public result contracts
  263. │ ├── browser/ # Focused DrissionPage capabilities and page scripts
  264. │ └── tools/ # 69 typed MCP tool definitions and thin adapters
  265. ├── tests/ # Unit tests
  266. └── playground/ # MCP Lab business-scenario playground
  267. ```
  268. **Key Principles**:
  269. - ✅ Type-safe Pydantic models for all tools
  270. - ✅ Async/await throughout
  271. - ✅ Clean separation of concerns
  272. - ✅ Comprehensive error handling
  273. - ✅ Unit and protocol test coverage for core tool registration/response behavior
  274. ---
  275. ## 🔧 Configuration
  276. ### Codex CLI / IDE (Recommended)
  277. ```toml
  278. [mcp_servers.drissionpage]
  279. command = "drissionpage-mcp"
  280. startup_timeout_sec = 20
  281. tool_timeout_sec = 60
  282. # Optional browser/runtime environment variables:
  283. # [mcp_servers.drissionpage.env]
  284. # CHROME_PATH = "/custom/path/to/chrome"
  285. # DP_HEADLESS = "1"
  286. ```
  287. You can also add it with the Codex CLI:
  288. ```bash
  289. codex mcp add drissionpage -- drissionpage-mcp
  290. ```
  291. If Codex/Cursor/Claude Desktop is launched from a GUI and cannot see your shell
  292. `PATH` or virtualenv, use the absolute Python executable instead:
  293. ```toml
  294. [mcp_servers.drissionpage]
  295. command = "/absolute/path/to/python"
  296. args = ["-m", "drissionpage_mcp.cli"]
  297. startup_timeout_sec = 20
  298. tool_timeout_sec = 60
  299. ```
  300. ### JSON MCP Clients
  301. ```json
  302. {
  303. "mcpServers": {
  304. "drissionpage": {
  305. "command": "drissionpage-mcp"
  306. }
  307. }
  308. }
  309. ```
  310. ### Advanced JSON Setup
  311. ```json
  312. {
  313. "mcpServers": {
  314. "drissionpage": {
  315. "command": "drissionpage-mcp",
  316. "args": ["--log-level", "DEBUG"],
  317. "env": {
  318. "CHROME_PATH": "/custom/path/to/chrome"
  319. }
  320. }
  321. }
  322. }
  323. ```
  324. Absolute-Python fallback for GUI clients:
  325. ```json
  326. {
  327. "mcpServers": {
  328. "drissionpage": {
  329. "command": "/absolute/path/to/python",
  330. "args": ["-m", "drissionpage_mcp.cli"],
  331. "env": {
  332. "CHROME_PATH": "/custom/path/to/chrome",
  333. "DP_HEADLESS": "1"
  334. }
  335. }
  336. }
  337. }
  338. ```
  339. ---
  340. ## 📋 Requirements
  341. - **Python 3.10+** (3.11+ recommended)
  342. - **Chrome or Chromium** browser
  343. - **Any MCP-compatible client**: Codex CLI/IDE, Claude Code, Claude Desktop, Cursor, VS Code, etc.
  344. ---
  345. ## 🧪 Testing
  346. ### Verify Installation
  347. ```bash
  348. # Environment diagnostics; add --launch-browser for a browser startup check
  349. drissionpage-mcp doctor
  350. drissionpage-mcp doctor --launch-browser
  351. # Source checkout tests
  352. python -m pip install -e ".[dev]"
  353. python -m pytest tests/
  354. # Coverage report (CI enforces the current 95% floor and uploads coverage.xml)
  355. python -m pytest tests/ --cov=drissionpage_mcp --cov-report=term-missing --cov-report=xml
  356. # Browser-backed MCP Lab scenario checks
  357. DP_HEADLESS=1 python playground/run_mcp_lab.py --all --json
  358. ```
  359. GitHub Actions runs lint, unit, protocol, package, browser integration, and
  360. coverage jobs. Codecov is configured through `codecov.yml` and the CI workflow.
  361. ### Try It Out
  362. ```bash
  363. # No-browser MCP registry check
  364. python playground/run_mcp_lab.py --case registry
  365. # Local deterministic site check
  366. python playground/run_mcp_lab.py --case site
  367. # Browser-backed form inspection scenario
  368. DP_HEADLESS=1 python playground/run_mcp_lab.py --case form-inspect
  369. ```
  370. ---
  371. ## 🚀 Use Cases
  372. ✅ **Automated Testing** - Test web applications
  373. ✅ **Data Scraping** - Extract structured data from websites
  374. ✅ **Form Automation** - Fill and submit forms
  375. ✅ **Monitoring** - Check for updates or changes
  376. ✅ **Screenshot Verification** - Capture and verify page state
  377. ✅ **Content Analysis** - Analyze web content programmatically
  378. ---
  379. ## 🐛 Troubleshooting
  380. ### Tools Not Loading?
  381. ```bash
  382. drissionpage-mcp --version
  383. ```
  384. Should output the installed package version, for example `drissionpage-mcp 0.9.0`.
  385. `drissionpage-mcp doctor` must also report both `mcp_supported` and
  386. `mcp_server_wiring` as `ok`; package-version output alone does not prove that an
  387. MCP client can initialize the server.
  388. ### Browser Issues?
  389. ```bash
  390. # Check browser installation
  391. which google-chrome # Linux
  392. which chromium # macOS
  393. ```
  394. ### Codex / MCP Client Not Finding Server?
  395. - Codex: run `codex mcp list`; in the TUI, run `/mcp`
  396. - JSON clients: verify config file path and JSON syntax
  397. - Restart Codex or your MCP client after changes
  398. - Check logs: `drissionpage-mcp --log-level DEBUG`
  399. See [docs/troubleshooting.md](docs/troubleshooting.md) for the complete troubleshooting guide.
  400. ---
  401. ## 📊 Project Status
  402. | Component | Status |
  403. |-----------|--------|
  404. | **Core Features** | ✅ Complete |
  405. | **Testing** | ✅ Strict unit/protocol/schema checks plus browser-backed scenarios |
  406. | **Documentation** | ✅ Setup, compatibility, troubleshooting, and public tool contracts |
  407. | **Package** | ✅ PyPI metadata and build checks |
  408. | **Status** | 🟡 Beta; real browser behavior depends on local Chrome/Chromium and target sites |
  409. **Version**: 0.9.0 development candidate | **License**: Apache 2.0 | **Maintained**: ✅ Active
  410. ---
  411. ## 🗺️ Roadmap
  412. ### Current candidate (v0.9.0)
  413. - [x] 69 atomic navigation, tab/frame/shadow, accessibility, observation, interaction, browser-environment, network, Cookie/storage, wait, and console tools, all loaded by default
  414. - [x] stdio MCP server integration
  415. - [x] Doctor diagnostics for local setup
  416. - [x] Stable JSON mirror, `structuredContent`, and typed per-tool MCP `outputSchema`
  417. - [x] Structured recovery hints in `error.details.hints` for common failures
  418. - [x] Sanitized browser failures with `DIALOG_PENDING`/`DIALOG_NOT_FOUND` recovery and strict standards-compliant JSON for non-finite JavaScript values
  419. - [x] Balanced `page_snapshot` output so link-heavy pages still expose controls and forms
  420. - [x] Optional case-insensitive literal `page_snapshot(query=...)` search with bounded, replayable continuation cursors tied to one tab and document generation
  421. - [x] Atomic type, select, check, click, keyboard, upload, wait, and state-read tools cover native controls and framework-driven widgets without library-specific branches
  422. - [x] Stable optional `tab_id` targeting across 63 tab-scoped tools, per-tab action serialization, target isolation, and draining close/cleanup semantics
  423. - [x] Tab management with `tab_list`, `tab_switch`, `tab_close`, and `page_navigate(new_tab=true, background=..., new_window=..., new_context=...)`
  424. - [x] Tab-owned network listener tokens, packet cursors, timeout evidence, cancellation-safe packet recovery, and deterministic close cleanup
  425. - [x] Observable actions with `page_observe`, `page_evaluate`, `wait_until`, and optional `observe=true` changes on navigation, click, and type
  426. - [x] Deadline-bounded `wait_until`, including `ready_state` waits, and optional `page_navigate(timeout=...)` evidence for final URL/readiness and non-negative navigation, settle, and total timing
  427. - [x] Console observability with `page_console_logs`, console summary in `page_observe`, and console change fields in `observe=true`
  428. - [x] Form, component-library, challenge, and convenience workflows remain outside the MCP core
  429. - [x] Repository example Skills for cross-origin iframes, authorized Turnstile fixtures, and bounded Xiaohongshu-like research are discoverable through the static catalog and excluded from wheel/sdist packages
  430. - [x] Capability-probed `page_dialog_respond`, additive double/context click behavior, and selector/coordinate/keyboard download correlation with safe `ArtifactRef` metadata
  431. - [x] Secret-bearing Web Storage values require `include_values=true`; keyboard and keyboard-download results expose redacted metadata only
  432. - [x] Per-tab download trigger locking, shared deadlines, cleanup/replay guarantees, and a 250ms fail-closed late-mission guard
  433. - [x] Reproducible W01-W08 public-tool benchmark with ten isolated runs per workload, machine-readable evidence, and zero duplicate side effects
  434. - [x] Network listener beta with `network_listen_start`, `network_listen_wait`, and `network_listen_stop` for HTTP/XHR/Fetch observation
  435. - [x] Public-response redaction for URLs, credentials, headers, Cookies, network bodies, errors, receipts, and text mirrors; listener waits are isolated from unrelated browser actions
  436. - [x] Browser-only request environment control with redacted header, user-agent, and blocked-URL write results plus cache-only clearing that preserves Cookies and Web Storage
  437. - [x] `direct` and deterministic bounded `natural` profiles for `page_pointer_move`, `page_pointer_drag`, and `page_click_xy`, with exact endpoints and failure-safe release
  438. - [x] Optional bounded `page_pointer_drag.waypoints` for one held multi-segment canvas, map, box-selection, or visual-editor gesture
  439. - [x] File upload, scrolling, hover, select/check, keyboard, iframe, shadow DOM, cookie, and storage tools for DrissionPage 4.x
  440. - [x] Pure browser Cookie set/get/delete/clear flow, including bounded batch writes whose successful results retain metadata with redacted values
  441. - [x] Ten-cycle controlled and validation input replacement through native DrissionPage input on the supported browser matrix
  442. - [x] Cross-origin OOPIF reads through `frame_*` and closed Shadow DOM lookup through DrissionPage-backed `shadow_*`, with narrower pointer targeting documented separately
  443. - [x] Frame boundary/document-access classification plus outer presentation, top-level viewport coordinate, scroll receipt, and coordinate-actionability evidence for production challenge workflows
  444. - [x] Local challenge-surface and opt-in official Turnstile test-key benchmarks with parent-page postconditions, screenshots, and token-safe evidence
  445. - [x] Backward-compatible string or structured selector/accessibility targets across element reads, actions, waits, uploads, and click-download correlation, resolving ordered frames first and then ordered Shadow DOM hosts
  446. - [x] Bounded accessibility snapshots, non-handling native dialog observation, and live element state/geometry for autonomous locate-act-verify loops
  447. - [x] Browser permission observation/set/reset, managed PDF/MHTML artifacts, automatic file chooser interception, and credential-redacted HTTP auth isolated by disposable Chromium context
  448. - [x] Chrome sandbox remains enabled by default; `DP_NO_SANDBOX=1` is reserved for restricted container/root environments
  449. - [x] No retained action history, generated code snippets, or absolute screenshot paths in public results
  450. - [x] Opt-in local safety policy for navigation and screenshot paths
  451. - [x] One optional-Skills catalog resource with repository example metadata, zero prompts, plus Skills, eval, compatibility, and troubleshooting documentation
  452. - [x] Structured navigation policy checks before browser startup, bounded Skills compatibility, and full-CI release artifact reuse
  453. - [x] Local 0.9.0 package metadata and clean-installed-package smoke coverage
  454. - [ ] Publish 0.9.0 to PyPI and the MCP Registry after release gates complete
  455. ---
  456. ## 📖 Integration Examples
  457. ### Codex CLI / IDE
  458. ```toml
  459. [mcp_servers.drissionpage]
  460. command = "drissionpage-mcp"
  461. startup_timeout_sec = 20
  462. tool_timeout_sec = 60
  463. ```
  464. Verify with:
  465. ```bash
  466. codex mcp list
  467. ```
  468. ### Claude Code
  469. ```json
  470. {
  471. "mcpServers": {
  472. "drissionpage": {
  473. "command": "drissionpage-mcp"
  474. }
  475. }
  476. }
  477. ```
  478. Config file: `~/.config/claude-code/mcp_settings.json` (macOS/Linux) or
  479. `%APPDATA%\claude-code\mcp_settings.json` (Windows).
  480. <p align="center">
  481. <img src="https://raw.githubusercontent.com/jumodada/Drissionpage-MCP-Server/assets/04-claude-code.png" width="700" alt="Claude Code mcp_settings.json">
  482. </p>
  483. ### Cursor
  484. ```json
  485. {
  486. "mcpServers": {
  487. "drissionpage": {
  488. "command": "drissionpage-mcp"
  489. }
  490. }
  491. }
  492. ```
  493. Config file: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project). You
  494. can also add it from **Cursor Settings → Tools & MCPs → New MCP Server**.
  495. <p align="center">
  496. <img src="https://raw.githubusercontent.com/jumodada/Drissionpage-MCP-Server/assets/05-cursor.png" width="700" alt="Cursor mcp.json">
  497. <br><br>
  498. <img src="https://raw.githubusercontent.com/jumodada/Drissionpage-MCP-Server/assets/08-cursor-ui.png" width="540" alt="Cursor Settings — add a new MCP server">
  499. </p>
  500. ### Claude Desktop
  501. ```json
  502. {
  503. "mcpServers": {
  504. "drissionpage": {
  505. "command": "drissionpage-mcp"
  506. }
  507. }
  508. }
  509. ```
  510. Once connected, the tools load automatically:
  511. <p align="center">
  512. <img src="https://raw.githubusercontent.com/jumodada/Drissionpage-MCP-Server/assets/07-connected.png" width="700" alt="MCP client with DrissionPage tools loaded">
  513. </p>
  514. ---
  515. ## 🤝 Contributing
  516. Contributions are welcome!
  517. 1. Fork the repository
  518. 2. Create a feature branch
  519. 3. Make focused changes
  520. 4. Run the relevant checks
  521. 5. Submit a pull request
  522. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, validation, and compatibility expectations.
  523. ---
  524. ## 🔒 Security
  525. - Runs locally in your environment
  526. - Uses a local browser that may have access to authenticated sessions, cookies, downloads, and page content
  527. - Can open and interact with any site reachable from the local machine
  528. - Does not require external API credentials
  529. **Best Practices**:
  530. - Use a dedicated browser profile for sensitive workflows
  531. - Review MCP client prompts before allowing actions on authenticated or production systems
  532. - Respect website terms of service, robots.txt, and rate limits
  533. - See [SECURITY.md](SECURITY.md) for reporting and safe-usage guidance
  534. ---
  535. ## 📄 License
  536. Licensed under **Apache License 2.0** - see [LICENSE](LICENSE)
  537. ---
  538. ## 📈 Statistics
  539. [![Downloads](https://pepy.tech/badge/drissionpage-mcp)](https://pepy.tech/project/drissionpage-mcp)
  540. [![PyPI Version](https://img.shields.io/pypi/v/drissionpage-mcp.svg?cacheSeconds=3600)](https://pypi.org/project/drissionpage-mcp/)
  541. ---
  542. ## 🌟 Show Your Support
  543. If you find this project useful, please consider:
  544. - ⭐ Starring on [GitHub](https://github.com/jumodada/Drissionpage-MCP-Server)
  545. - 📤 Sharing with your network
  546. - 💬 Leaving feedback or suggestions
  547. - 🐛 Reporting issues to help improve
  548. ---
  549. **Made with ❤️ by [Wukunyun](https://github.com/jumodada)**
  550. **Ready to automate your workflows?** Install now: `python -m pip install -U drissionpage-mcp`
  551. ---
  552. ## 🆕 Current Candidate: v0.9.0
  553. Candidate dated 2026-10-20. This is the current local implementation, not a claim of external publication or a completed hosted multi-platform CI run:
  554. - Opt-in navigation allow/block URL rules use structured origin and path-boundary matching instead of raw string prefixes. Host-only rules continue to include subdomains.
  555. - Denied `page_navigate` and `page_navigate_with_http_auth` calls return `POLICY_DENIED` before initializing Chromium, creating a tab, or applying auth credentials.
  556. - Matching is an operator-side navigation check, not a complete network sandbox: it does not constrain redirects, page scripts, iframes, DNS rebinding, or later browser requests.
  557. - Skills metadata accepts MCP 0.9.0 within bounded compatibility ranges while retaining schema v2, the fixed `skills-manager` `v0.8.4` revision, and existing content hashes. Remote validation currently fails because pinned raw GitHub URLs return HTTP 404.
  558. - Release tags run the complete CI workflow before upload and reuse the exact SHA256-verified wheel and sdist artifacts that passed package smoke tests.
  559. - The public surface remains 69 tools, zero prompts, and one static Skills catalog resource. No runtime dependency or capability profile was added.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.