DrissionPage MCP

DrissionPage MCP 服务

为 Codex、Claude Code 和 MCP 客户端提供专业的浏览器自动化，由 DrissionPage 驱动。

DrissionPage 是一个 Python 网页自动化库，基于直接控制 Chromium/CDP，并支持 requests 风格的 HTTP 会话。此服务将面向浏览器的功能封装为类型化、原子化的 MCP 工具。

打开交互式浏览器实验室，重放有界的自然指针移动，拖动控件，并验证可观察状态。

官方代码仓库：GitHub | GitCode

English Version | 中文版本

🖱️ 具有自然指针移动效果的原子化浏览器控制

DrissionPage MCP 0.8.8 提供 69 项类型化浏览器功能。 MCP 服务提供准确的底层观察与交互；客户端或可选的 Skill 可组合这些功能，以适用于网站、组件库、挑战或业务工作流。

模型决定要做什么；MCP 会准确执行所请求的浏览器操作。

Screenshot / page observation
        ↓
Multimodal model identifies viewport coordinates
        ↓
page_click_xy(x=442, y=369, profile="natural")
        ↓
24-step eased cubic path → exact target → press → release
        ↓
Observe and verify the resulting page state

核心交互保证

• 两种有界配置：direct 执行一次精确移动；natural 执行确定性的 24 步缓动三次贝塞尔路径，间隔可重现，为 8-14ms，并精确到达终点。
• 没有隐藏的随机性：相同的起点、目标和配置会产生相同的路径；不会抖动、过冲或执行反检测逻辑。指针位置会保留状态，因此重复调用可能从上一次的终点开始。
• 明确的操作序列：点击由所选移动配置、可选的调用方指定延迟、按下和释放组成；拖动会在所选路径和有序航点上保持按下状态。
• 输入失败安全：如果按下后执行失败，会释放已按下的指针按钮。
• 实时浏览器证据：对于基于选择器的拖动操作，会在操作前立即解析选择器几何信息。
• 类型化结果：输出会报告已执行的坐标、按钮、步骤数和明确的延迟元数据。

存在可靠选择器时，请使用结构化 DOM 目标。对于画布控件、编辑器、地图、图表和其他纯视觉界面，请使用坐标、natural 移动和明确的拖动航点。特定组件的目标发现、挑战观察、多次点击排序、登录流程及其他业务策略，属于客户端或可选 Skill 的职责。

{
  "x": 442,
  "y": 369,
  "profile": "natural",
  "button": "left",
  "element": "visually identified control"
}

专为获得授权的浏览器自动化、测试、无障碍工作流和技术研究而设计。核心不提供特定挑战或特定网站的工作流。

🧭 客户端设置导航

• 原子化浏览器控制
• 安装与截图演示
• Codex CLI/IDE 快速设置
• Codex CLI/IDE 集成示例
• Skills 和可复用流程
• Claude Code 设置
• Cursor 设置
• Claude Desktop 设置
• 故障排除

---

🚀 DrissionPage MCP 是什么？

DrissionPage MCP Server 是一个本地 Model Context Protocol（MCP）服务，可为 Codex CLI/IDE、Claude Code、Claude Desktop 和其他 MCP 客户端提供 DrissionPage 浏览器自动化工具。

独立服务提供 69 个类型化工具、零个 MCP 提示词，以及一个静态的可选 Skills 目录资源。0.8.8 版本保持注册表稳定，同时新增了带关联信息的网络监听器代次、显式数据包游标、超时证据、取消恢复和由标签页管理的清理机制。所有工具默认加载；没有功能配置文件或可选启用的 full 模式。模型会组合这些原子化能力，而可复用的挑战和网站流程则作为可选 Skills 放在发行包之外。浏览器执行由 DrissionPage 提供支持。

🌟 为什么选择 DrissionPage MCP？

• 结构优先，支持视觉交互：有 DOM 结构时使用该结构；视觉交互更合适时使用多模态坐标
• 确定性：可靠地选择元素，并对 CSS/XPath 进行规范化，使选择器更适合大模型使用
• 自然指针移动：通过相同的原子化工具，支持精确直接移动和有界、确定性的 24 步缓动轨迹
• 快速轻量：基于 DrissionPage 高效的引擎构建，开销极低
• 类型安全：所有工具均提供完整的类型提示和 Pydantic 验证
• 便于开源协作：包含兼容性说明、故障排除指南和 CI 检查，便于长期维护和贡献
• 易于集成：只需简单的 pip install，再配置 Codex TOML 或 MCP JSON

✅ 质量与真实场景验证

DrissionPage MCP 通过严格的回归测试套件和基于浏览器的场景检查进行验证：

• 严格的自动化测试：CI 中运行单元、协议、架构快照、响应契约、资源、发行版元数据、安全策略、浏览器集成和覆盖率检查。
• 95% 覆盖率下限：CI 强制执行当前 95% 的覆盖率门槛，并上传覆盖率报告。
• 真实浏览器验证：基于 Chrome/Chromium 的集成测试会调用提供给客户端的同一批 MCP 工具。
• 文档边界验证：针对性的浏览器测试可验证跨源 OOPIF 读取，以及通过 DrissionPage 暴露的封闭 Shadow DOM 查询，且不会使用 JavaScript 穿透回退方案。
• 挑战界面验证：本地测试夹具涵盖常规、隐藏、视口外、延迟加载和 CSS 3D 跨源小组件；官方 Turnstile 虚拟密钥涵盖可见、不可见、通过、失败和强制交互回调，且不会保留令牌。
• 场景验证：playground MCP Lab 涵盖真实表单、电商页面、社交动态、时间线、动态等待、iframe 场景和恢复路径，无需依赖公开演示网站。

---

⚡ 首次成功路径

# Install or update Codex CLI (macOS/Linux)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Install from PyPI
python -m pip install -U "drissionpage-mcp>=0.8.8"

# Verify package and environment
drissionpage-mcp --version
drissionpage-mcp doctor

官方安装程序也会更新现有的 Codex CLI 安装。关于 Windows 和 Codex 桌面应用，请参阅官方 Codex CLI 和应用文档。

然后添加下方的 Codex 或 MCP 客户端配置，并重启客户端。

---

📦 在 Codex CLI/IDE 中设置（30 秒）

Codex 通过 config.toml 支持本地 stdio MCP 服务；CLI 和 IDE 扩展共用同一份 MCP 配置。

1. 编辑 Codex 配置：

   • 用户级：~/.codex/config.toml
   • 项目级：受信任项目中的 .codex/config.toml

2. 添加以下配置：

   [mcp_servers.drissionpage]
   command = "drissionpage-mcp"
   startup_timeout_sec = 20
   tool_timeout_sec = 60
   

3. 重启 Codex。在 TUI 中运行 /mcp；在 shell 中运行 codex mcp list。

Claude Code、Claude Desktop 和其他基于 JSON 的 MCP 客户端，请参阅集成示例。

---

🎯 快速示例

导航并截图

"Visit https://example.com and take a screenshot for me"

搜索并提取

"Go to Wikipedia, search for Python, and get the first paragraph"

表单自动化

"Fill out the form at https://httpbin.org/forms/post and submit it"

数据抓取

"Get the top 10 news headlines from news.ycombinator.com"

---

🛠️ 69 个强类型浏览器工具

所有 63 个标签页范围内的工具都接受可选的 tab_id。省略该参数时，会在调用开始时获取当前 MCP 标签页；也可以传入 MCP/原生 DrissionPage 标签页 ID 以明确指定目标。成功的标签页范围内操作会返回解析后的 MCP tab_id；不同标签页可以并发运行，而同一标签页上的操作仍按顺序执行。

🌐 导航（5 个工具）

• page_navigate - 导航至任意 URL；指定已有 tab_id，或将 new_tab=true 与可选的 background、new_window 或 new_context 组合使用；observe 会返回变更摘要
• page_navigate_with_http_auth - 在专用的一次性 Chromium 上下文中通过受限的 HTTP 身份验证质询进行导航，且不会返回凭据
• page_go_back - 在浏览器历史记录中后退
• page_go_forward - 在浏览器历史记录中前进
• page_refresh - 重新加载当前页面

🗂️ 标签页操作（3 个工具）

• tab_list - 列出已打开的浏览器标签页及其稳定的 MCP 标签页 ID
• tab_switch - 切换到 tab_list 返回的标签页
• tab_close - 拒绝新任务，等待进行中的操作完成，然后关闭一个标签页，而不关闭整个浏览器

🎯 元素交互与提取（16 个工具）

• element_find - 通过 CSS 选择器或 XPath 查找一个元素；h1 这类未加前缀的选择器会被视为 CSS
• element_find_all - 提取有数量限制的重复元素及其文本、属性和推荐选择器
• element_click - 点击任意元素，支持左键、右键、中键以及单击、双击语义
• element_click_and_download - 将一个选择器、坐标或键盘触发操作与 DP_MCP_DOWNLOAD_ROOT 下一个经过完整性检查的文件相关联
• element_type - 在元素中输入文本
• element_upload_file - 使用 element_upload_file(paths=[...]) 将 DP_MCP_UPLOAD_ROOT 中的文件上传到 input[type=file]
• element_click_and_upload - 启用 Chromium 文件选择器，点击其触发元素，注入获准的文件，并清除拦截，无需调用操作系统文件选择器
• element_scroll_into_view - 将元素滚动到视口内，以便进行操作
• element_hover - 将鼠标悬停在元素上，以触发菜单/工具提示状态
• element_select - 按值、文本或索引选择选项
• element_check - 选中或取消选中复选框/单选控件
• element_get_text - 获取元素或页面文本
• element_get_attribute - 获取 HTML 属性
• element_get_property - 获取实时 DOM 属性，例如输入值
• element_get_html - 获取元素或页面 HTML
• element_state_get - 读取单个元素的实时 DrissionPage 状态标志以及文档/视口几何信息

📸 页面操作（18 个工具）

• page_screenshot - 捕获内嵌的整页或视口截图
• page_screenshot_save - 将截图保存到 DP_MCP_SCREENSHOT_ROOT 下
• page_export_artifact - 在 DP_MCP_ARTIFACT_ROOT 下生成受管理的 PDF 或 MHTML 产物，并提供 SHA-256 和回执证据
• page_snapshot - 返回范围受限的页面大纲，包含标题、链接、按钮、输入框、表单和选择器建议
• page_accessibility_snapshot - 返回页面或指定元素的范围受限的 Chromium 无障碍树；除非明确请求，否则会对字段值进行脱敏
• page_observe - 返回精简的页面指纹，包含 URL、标题、计数、可见文本示例、活动元素和近期控制台摘要
• page_evaluate - 在当前页面运行范围受限的 JavaScript，并返回 JSON 安全的结果
• page_scroll - 使用 page_scroll(pixels=...) 进行相对滚动，或传入 x/y 指定绝对位置
• keyboard_press - 向活动元素/页面发送按键，不会在结果中回显输入内容
• page_resize - 调整浏览器窗口大小
• page_pointer_move - 以 direct 或范围受限的确定性 natural 运动移至精确的视口 CSS 坐标
• page_pointer_drag - 使用所选配置文件执行一次安全失败的坐标拖动，最多支持六个可选的有序路径点
• page_pointer_drag_element - 在拖动前立即解析源和目标的几何信息；支持顶层文档或同源 iframe 中的 CSS/XPath，以及通过嵌套开放 Shadow DOM 宿主的 CSS 路径
• page_click_xy - 使用 direct 或 natural 运动移动，可选择等待明确指定的延迟，然后在精确目标位置按下并释放
• page_close - 关闭浏览器
• page_get_url - 获取当前 URL
• page_dialog_observe - 等待并检查待处理的原生警报、确认框或提示框，但不进行处理
• page_dialog_respond - 使用 page_dialog_respond(action="accept")（或 "dismiss"）处理一个待处理的警报、确认框或提示框

🧱 框架 / Shadow DOM（5 个工具）

• frame_list - 列出 iframe/frame 上下文，不更改全局框架状态
• frame_snapshot - 使用 frame_snapshot(frame_selector="...") 或 frame_index 检查一个 iframe，并获取范围受限的大纲数据
• frame_find - 在选定的 iframe 内查找元素
• shadow_find - 在当前受支持的 DrissionPage 运行时所暴露的 Shadow Root 中查找一个元素，包括经过测试的封闭根
• shadow_find_all - 从 DrissionPage 暴露的 Shadow Root 中提取重复元素

🌍 浏览器环境（6 个工具）

• browser_headers_set - 替换额外的请求头，并返回经脱敏的值；传入空对象可清除请求头
• browser_user_agent_set - 覆盖 User Agent 和可选的平台，并返回当前接受的值和之前的值
• browser_cache_clear - 清除 HTTP 缓存，同时保留 Cookies、localStorage 和 sessionStorage
• browser_permission_get - 查询当前文档源的一项浏览器权限，不会打开操作系统提示
• browser_permission_set - 对确切的源/当前 Chromium 上下文使用 browser_permission_set(setting="granted")（或 "denied"/"prompt"）
• browser_permissions_reset - 重置当前 Chromium 上下文的权限覆盖项

🍪 Cookie 与存储（7 个工具）

• browser_cookies_get - 读取规范化的 Cookies，默认对值进行脱敏
• browser_cookies_set - 一次调用最多设置 100 个 Cookies，并返回经脱敏的已接受元数据
• browser_cookies_delete - 删除指定名称的 Cookie，可选按 URL/域/路径限定范围
• browser_cookies_clear - 清除所有浏览器 Cookies
• storage_get - 按键或以映射形式读取 localStorage/sessionStorage；除非 include_values=true，否则会对值进行脱敏
• storage_set - 设置一项 localStorage/sessionStorage 条目，不会回显其值
• storage_clear - 清除一个存储键或整个存储区域

🧪 调试 / 可观测性（1 个工具）

• page_console_logs - 按级别筛选、使用游标分页并设置限制，读取数量受限的浏览器控制台消息

⏱️ 等待操作（4 个工具）

• wait_for_element - 等待元素出现（可设置超时）
• wait_for_url - 使用 wait_for_url(url_pattern="...")，直到当前 URL 包含指定文本
• wait_until - 使用 wait_until(condition="text_contains", value="...") 或其他有文档说明的条件 / 值组合
• wait_time - 延迟执行

🌐 网络控制与观察（4 个工具）

• network_listen_start - 通过 DrissionPage 开始有界的 HTTP/XHR/Fetch 观察
• network_listen_wait - 等待有界的数据包元数据，可选择获取已脱敏的标头或正文摘录
• network_listen_stop - 停止观察，并可选择清除排队的数据包
• network_blocked_urls_set - 使用 network_blocked_urls_set(urls=[...]) 替换被阻止的 URL 模式；空列表会清除这些模式

🧩 可选技能发现

• 资源：drissionpage://skills/catalog
• 提示词：无
• 仓库示例：cross-origin-iframe-probe、turnstile-testing 和 xiaohongshu-content-research
• 入口：skills/<skill-name>/SKILL.md；目录架构 v2 包含 Skill/MCP 版本、所需工具、fixture、固定的 v0.8.4 源码修订版本、验证状态和 SHA-256
• 技能是供 MCP 主机使用的 Markdown 操作流程。它们不是 Python 模块，不由服务执行，也不包含在 wheel/sdist 软件包中。

使用 python playground/validate_skills.py --json 验证源码检出。

使用 python install.py install --client codex --json 或 python install.py install --client claude --json 安装固定的目录版本 [email protected]。

📖 技能与可复用操作流程

MCP 核心提供原子级浏览器操作。技能则在服务外提供可复用、可审查的操作流程：

示例技能	演示内容	停止边界
cross-origin-iframe-probe	框架发现、跨域诊断、坐标回退和外部验证	无法读取跨域 iframe 的内部 DOM
turnstile-testing	Cloudflare 测试 fixture、经授权的生产环境挑战交互、坐标几何信息和父页面检查	使用有文档说明的支持矩阵，并验证最终页面状态
xiaohongshu-content-research	有界的只读笔记研究和确定性的 social-notes fixture	遇到 robots、登录、验证码、安全页面或速率限制时停止

发布新操作流程前，请阅读完整的 技能指南。 技能必须使用现有的类型化工具、收集最新证据、验证后置条件、脱敏机密并说明不支持的情况。它们不会添加新的 MCP 工具，也不会覆盖服务的导航和安全策略。多标签页技能应在后续的标签页作用域调用中传递返回的 MCP tab_id，而不是依赖可变的当前标签页状态。

---

📚 文档

指南	说明
README.md	安装、工具和架构
docs/compatibility.md	支持的 Python、DrissionPage、MCP 和浏览器版本
docs/tool-contract.md	公开的 MCP 工具名称、输入、注解和响应结构
docs/troubleshooting.md	Doctor 命令、浏览器启动和客户端设置修复
CHANGELOG.md	版本说明

---

🏗️ 架构

采用简洁、模块化的设计：

DrissionMCP/
├── drissionpage_mcp/
│   ├── cli.py              # Process entry point
│   ├── server.py           # MCP transport and request routing
│   ├── context.py          # Browser and tab lifecycle facade
│   ├── runtime.py          # Operation keys, receipts, artifacts, and capability state
│   ├── tool_outputs.py     # Typed public result contracts
│   ├── browser/            # Focused DrissionPage capabilities and page scripts
│   └── tools/              # 69 typed MCP tool definitions and thin adapters
├── tests/                  # Unit tests
└── playground/             # MCP Lab business-scenario playground

核心原则：

• ✅ 所有工具均使用类型安全的 Pydantic 模型
• ✅ 全面使用 Async/await
• ✅ 清晰划分职责
• ✅ 全面的错误处理
• ✅ 覆盖核心工具注册和响应行为的单元测试与协议测试

---

🔧 配置

Codex CLI / IDE（推荐）

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

也可以使用 Codex CLI 添加：

codex mcp add drissionpage -- drissionpage-mcp

如果通过图形界面启动 Codex/Cursor/Claude Desktop，且无法访问 shell PATH 或虚拟环境，请改用绝对路径指定 Python 可执行文件：

[mcp_servers.drissionpage]
command = "/absolute/path/to/python"
args = ["-m", "drissionpage_mcp.cli"]
startup_timeout_sec = 20
tool_timeout_sec = 60

JSON MCP 客户端

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

高级 JSON 配置

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp",
      "args": ["--log-level", "DEBUG"],
      "env": {
        "CHROME_PATH": "/custom/path/to/chrome"
      }
    }
  }
}

图形界面客户端的 Python 绝对路径备用方案：

{
  "mcpServers": {
    "drissionpage": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "drissionpage_mcp.cli"],
      "env": {
        "CHROME_PATH": "/custom/path/to/chrome",
        "DP_HEADLESS": "1"
      }
    }
  }
}

---

📋 要求

• Python 3.10+（推荐使用 3.11+）
• Chrome 或 Chromium 浏览器
• 任意兼容 MCP 的客户端：Codex CLI/IDE、Claude Code、Claude Desktop、Cursor、VS Code 等

---

🧪 测试

验证安装

# 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

# Browser-backed MCP Lab scenario checks
DP_HEADLESS=1 python playground/run_mcp_lab.py --all --json

GitHub Actions 会运行 lint、单元测试、协议测试、包测试、浏览器集成测试和 覆盖率任务。Codecov 通过 codecov.yml 和 CI 工作流进行配置。

试用

# No-browser MCP registry check
python playground/run_mcp_lab.py --case registry

# Local deterministic site check
python playground/run_mcp_lab.py --case site

# Browser-backed form inspection scenario
DP_HEADLESS=1 python playground/run_mcp_lab.py --case form-inspect

---

🚀 使用场景

✅ 自动化测试 - 测试 Web 应用 ✅ 数据抓取 - 从网站提取结构化数据 ✅ 表单自动化 - 填写并提交表单 ✅ 监控 - 检查更新或变化 ✅ 截图验证 - 捕获并验证页面状态 ✅ 内容分析 - 以编程方式分析网页内容

---

🐛 故障排除

工具未加载？

drissionpage-mcp --version

应输出已安装的软件包版本，例如 drissionpage-mcp 0.8.8。

drissionpage-mcp doctor 还必须将 mcp_supported 和 mcp_server_wiring 都报告为 ok；仅输出软件包版本并不能证明 MCP 客户端能够初始化服务。

浏览器问题？

# Check browser installation
which google-chrome    # Linux
which chromium         # macOS

Codex / MCP 客户端找不到服务？

• Codex：运行 codex mcp list；在 TUI 中运行 /mcp
• JSON 客户端：检查配置文件路径和 JSON 语法
• 修改后重启 Codex 或 MCP 客户端
• 查看日志：drissionpage-mcp --log-level DEBUG

请参阅docs/troubleshooting.md，了解完整的故障排除指南。

---

📊 项目状态

组件	状态
核心功能	✅ 完成
测试	✅ 严格的单元测试、协议测试和架构检查，以及由浏览器支持的场景测试
文档	✅ 设置、兼容性、故障排除和公开工具契约
软件包	✅ PyPI 元数据和构建检查
状态	🟡 Beta；实际浏览器行为取决于本地 Chrome/Chromium 和目标网站

版本：0.8.8 | 许可证：Apache 2.0 | 维护状态：✅ 正在积极维护

---

🗺️ 路线图

当前（v0.8.8）

• 69 个原子化导航、标签页／框架／Shadow DOM、无障碍、观察、交互、浏览器环境、网络、Cookie／存储、等待和控制台工具，默认全部加载
• stdio MCP 服务集成
• 用于本地设置的 Doctor 诊断
• 稳定的 JSON 镜像、structuredContent 和每个工具都有类型定义的 MCP outputSchema
• 在 error.details.hints 中为常见故障提供结构化恢复提示
• 清理后的浏览器故障信息，支持 DIALOG_PENDING／DIALOG_NOT_FOUND 恢复机制，并针对非有限 JavaScript 值严格遵守标准的 JSON 格式
• 平衡 page_snapshot 输出，让链接密集型页面仍能显示控件和表单
• 原子化的 type、select、check、click、keyboard、upload、wait 和 state-read 工具覆盖原生控件与框架驱动的组件，无需针对特定库进行分支处理
• 63 个按标签页作用域划分的工具支持稳定的可选 tab_id 定向、每个标签页的操作串行化、跨标签页并行处理，以及关闭／清理时的任务排空语义
• 标签页管理支持 tab_list、tab_switch、tab_close 和 page_navigate(new_tab=true, background=..., new_window=..., new_context=...)
• 标签页拥有的网络监听器令牌、数据包游标、超时证据、支持安全取消的数据包恢复，以及确定性的关闭清理
• 通过 page_observe、page_evaluate、wait_until 观察操作，并可选在导航、点击和输入操作中使用 observe=true
• 控制台可观察性支持 page_console_logs、page_observe 中的控制台摘要，以及 observe=true 中的控制台变更字段
• 表单、组件库、验证挑战和便捷工作流均不属于 MCP 核心
• 仓库示例 Skills 涵盖跨源 iframe、经授权的 Turnstile 测试夹具和有限范围的小红书风格研究，可通过静态目录发现，并且不会包含在 wheel／sdist 包中
• 基于能力探测的 page_dialog_respond、附加的双击／右键行为，以及与选择器／坐标／键盘下载关联并带有安全 ArtifactRef 元数据的功能
• 含敏感信息的 Web Storage 值需要设置 include_values=true；键盘和键盘下载结果仅公开经过脱敏的元数据
• 每个标签页的下载触发锁、共享截止时间、清理／重放保障，以及 250ms 的故障关闭式延迟任务防护
• 可复现的 W01-W08 公共工具基准测试；每种工作负载独立运行十次，提供机器可读证据，且不会产生重复副作用
• 网络监听 Beta 版支持使用 network_listen_start、network_listen_wait 和 network_listen_stop 观察 HTTP／XHR／Fetch
• 对公开响应中的 URL、凭据、标头、Cookie、网络正文、错误、回执和文本镜像进行脱敏；监听器等待与无关的浏览器操作相互隔离
• 仅控制浏览器请求环境；标头、用户代理和屏蔽 URL 的写入结果会脱敏；仅清除缓存，同时保留 Cookie 和 Web Storage
• page_pointer_move、page_pointer_drag 和 page_click_xy 支持 direct 及确定性、有界的 natural 配置，提供精确端点和失败安全释放机制
• 可选的有界 page_pointer_drag.waypoints，用于单次按住指针完成多段画布、地图、框选或视觉编辑器手势
• 适用于 DrissionPage 4.x 的文件上传、滚动、悬停、选择／勾选、键盘、iframe、Shadow DOM、Cookie 和存储工具
• 纯浏览器 Cookie 设置／获取／删除／清除流程，包括有界批量写入；成功结果保留元数据，同时对值进行脱敏
• 在受支持的浏览器矩阵中，通过原生 DrissionPage 输入控件进行十轮可控输入替换和验证输入替换
• 通过 frame_* 读取跨源 OOPIF，并通过 DrissionPage 支持的 shadow_* 查找封闭式 Shadow DOM；更有限的指针定向支持另有说明
• 对框架边界／文档访问进行分类，并为生产环境验证挑战工作流提供外层呈现、顶层视口坐标、滚动回执和坐标可操作性证据
• 本地验证挑战界面和选择启用的官方 Turnstile 测试密钥基准测试，提供父页面后置条件、截图和令牌安全证据
• 元素读取、操作、等待、上传和点击下载关联均向后兼容字符串或结构化选择器／无障碍目标；先按顺序解析框架，再按顺序解析 Shadow DOM 宿主
• 有界无障碍快照、不处理原生对话框的观察，以及实时元素状态／几何信息，支持自主定位－操作－验证循环
• 浏览器权限观察／设置／重置、受管理的 PDF／MHTML 制品、自动文件选择器拦截，以及通过一次性 Chromium 上下文隔离且凭据经过脱敏的 HTTP 身份验证
• 默认启用 Chrome 沙箱；DP_NO_SANDBOX=1 仅用于受限的容器／root 环境
• 公开结果中不保留操作历史、生成的代码片段或绝对截图路径
• 可选的本地安全策略，用于导航和截图路径
• 一个可选 Skills 目录资源，包含仓库示例元数据，不含提示词；另有 Skills、评估、兼容性和故障排除文档
• PyPI 分发
• 官方 MCP Registry 包元数据和通过标签触发的发布工作流

---

📖 集成示例

Codex CLI / IDE

[mcp_servers.drissionpage]
command = "drissionpage-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60

验证方式：

codex mcp list

Claude Code

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

配置文件：~/.config/claude-code/mcp_settings.json（macOS/Linux）或 %APPDATA%\claude-code\mcp_settings.json（Windows）。

Cursor

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

配置文件：~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）。你 也可以通过 Cursor 设置 → Tools & MCPs → New MCP Server 添加。

Claude Desktop

{
  "mcpServers": {
    "drissionpage": {
      "command": "drissionpage-mcp"
    }
  }
}

连接后，工具会自动加载：

---

🤝 参与贡献

欢迎贡献！

1. Fork 此代码仓库
2. 创建功能分支
3. 进行针对性修改
4. 运行相关检查
5. 提交拉取请求

有关设置、验证和兼容性要求，请参阅 CONTRIBUTING.md。

---

🔒 安全

• 在你的本地环境中运行
• 使用的本地浏览器可能有权访问已通过身份验证的会话、Cookie、下载内容和页面内容
• 可以打开并与本地计算机可访问的任何网站交互
• 无需外部 API 凭据

最佳实践：

• 为敏感工作流使用专用浏览器配置文件
• 在允许对已通过身份验证的系统或生产系统执行操作前，检查 MCP 客户端提示
• 遵守网站服务条款、robots.txt 和速率限制
• 有关报告问题和安全使用指南，请参阅 SECURITY.md

---

📄 许可证

采用 Apache License 2.0 许可——请参阅 LICENSE

---

📈 统计数据

---

🌟 支持我们

如果你觉得这个项目有用，请考虑：

• ⭐ 在 GitHub 上点星
• 📤 与你的社交网络分享
• 💬 留下反馈或建议
• 🐛 报告问题，帮助改进

---

由 Wukunyun 用 ❤️ 打造

准备好自动化你的工作流了吗？ 立即安装：python -m pip install -U drissionpage-mcp

---

🆕 最新版本：v0.8.8

发布于 2026-09-08。此版本保留了 69 个工具的注册表，同时明确并完善了网络监听器的生命周期管理：

• network_listen_start 会为每一代监听器返回新的 listener_token、生命周期状态、数据包游标和启动耗时。
• network_listen_wait 接受该令牌，并报告累计消耗量、单调递增的数据包索引、已用时间、明确的超时状态以及剩余超时时间。
• network_listen_stop 使用过期令牌时会返回 LISTENER_NOT_FOUND，防止旧任务停止同一标签页上的替代监听器。
• 取消等待时，会保留 DrissionPage 已移除的数据包；关闭标签页时，会在原生销毁前尽力停止监听器并清理队列。
• 真实 Chromium 测试会隔离不同标签页的监听器，并运行 100 次启动/停止循环，不留下活动驱动程序或队列残留。公共接口仍包含 69 个工具、零个提示词和一个 Skills 目录资源。