{"_id":"@a3180623/patchright-mcp","name":"@a3180623/patchright-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@a3180623/patchright-mcp","version":"1.0.0","description":"A streamlined MCP server for Patchright browser automation","main":"dist/index.js","bin":{"patchright-mcp":"dist/index.js"},"type":"module","scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts"},"dependencies":{"@modelcontextprotocol/sdk":"^1.11.0","patchright":"1.57.0","uuid":"^9.0.1","zod":"^3.22.4"},"devDependencies":{"@types/node":"^20.11.0","typescript":"^5.3.3"},"gitHead":"f8a3d351291d21a427aefa861e8b6863ddf18f42","types":"./dist/index.d.ts","_id":"@a3180623/patchright-mcp@1.0.0","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-y5Zf8KEMHRU3AFtS8NlmXuLtFlV1J8vzq/flPgCjMi0B+0H+uDYdPy72hnQ1ozuve72D7kUje9fVZfo2i1au3g==","shasum":"5d362d2e51bbfd5b32bb1ccf7aacd23127d39bb1","tarball":"https://registry.npmjs.org/@a3180623/patchright-mcp/-/patchright-mcp-1.0.0.tgz","fileCount":6,"unpackedSize":220762,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAU6GT67yrKj8bHg53gOt+VfZ42H7Yvr13R4QfUxk14wAiEAkpOT8JNpMCeOUR5QLCFiGXDBEUgWgDtGZJG6KCsnK+w="}]},"_npmUser":{"name":"a3180623","email":"3180623@gmail.com"},"directories":{},"maintainers":[{"name":"a3180623","email":"3180623@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/patchright-mcp_1.0.0_1770097883693_0.6661891863467744"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-03T05:51:23.529Z","1.0.0":"2026-02-03T05:51:23.840Z","modified":"2026-02-03T05:51:24.090Z"},"maintainers":[{"name":"a3180623","email":"3180623@gmail.com"}],"description":"A streamlined MCP server for Patchright browser automation","readme":"# Patchright MCP\n\n[中文](#中文) | [English](#english)\n\n---\n\n## 中文\n\n基于 **Patchright Node.js SDK**（Playwright 兼容 + 隐身增强）的 MCP（Model Context Protocol）服务器。专为 AI 代理设计，提供完整的浏览器自动化能力。\n\n### ✨ 核心特性\n\n| 特性 | 说明 |\n|------|------|\n| 🎭 **隐身浏览** | 基于 Patchright，绕过常见反爬检测（CDP/Webdriver 指纹等） |\n| 🎯 **ARIA Snapshot + Ref 定位** | 用 `browser_snapshot(type=\"aria\")` 产出带 `ref` 的快照，精准元素交互 |\n| 🔄 **会话持久化** | 默认使用持久化 profile 保留登录态，免重复登录 |\n| 📦 **结构化响应** | 返回 `result/code/tabs/console/downloads/page/snapshot/images` |\n| 🧹 **磁盘治理** | `browser_cleanup` 清理临时文件，防止无限增长 |\n| 🌐 **HTTP 扩展** | `request` / `wait_for_response` 用浏览器上下文发请求（带 Cookie） |\n\n### 📋 环境要求\n\n- **Node.js** 18+\n- **npm** 或 **pnpm**\n\n### 🚀 快速使用（无需下载源码）\n\n#### 方法 1：npx 直接运行（推荐）\n\n```bash\nnpx patchright-mcp\n```\n\nClaude Desktop 配置：\n```json\n{\n  \"mcpServers\": {\n    \"patchright\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"patchright-mcp\"]\n    }\n  }\n}\n```\n\n#### 方法 2：全局安装\n\n```bash\n# 从 npm 安装\nnpm install -g patchright-mcp\n\n# 或从 GitHub 直接安装\nnpm install -g github:Frankieli123/patchright-mcp\n\n# 运行\npatchright-mcp\n```\n\nClaude Desktop 配置：\n```json\n{\n  \"mcpServers\": {\n    \"patchright\": {\n      \"command\": \"patchright-mcp\"\n    }\n  }\n}\n```\n\n#### 方法 3：Docker 运行\n\n```bash\n# 构建镜像\ndocker build -t patchright-mcp https://github.com/Frankieli123/patchright-mcp.git\n\n# 运行\ndocker run -it patchright-mcp\n```\n\n### 📦 从源码安装\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Frankieli123/patchright-mcp.git\ncd patchright-mcp\n\n# 安装依赖\nnpm ci\n\n# 构建项目\nnpm run build\n```\n\n**安装浏览器二进制**（二选一）：\n\n```bash\n# 方式 1：命令行安装\nnpx patchright install chromium\n\n# 方式 2：通过 MCP 工具安装（适合远程/容器环境）\n# 调用 browser_install 工具\n```\n\n### ▶️ 运行\n\n```bash\n# 生产模式\nnpm start\n\n# 开发模式（热重载）\nnpm run dev\n```\n\n**可选能力控制**（通过 `--caps` 或环境变量 `PATCHRIGHT_MCP_CAPS`）：\n\n```bash\n# 仅启用 vision 和 pdf 能力\nnpm start -- --caps=vision,pdf\n\n# 启用所有能力\nnpm start -- --caps=all\n```\n\n### 🔧 集成配置\n\n#### Claude Desktop\n\n编辑 `claude-desktop-config.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"patchright\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/patchright-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n#### Amp / VS Code\n\n在 `.amp/settings.json` 或项目配置中添加：\n\n```json\n{\n  \"mcpServers\": {\n    \"patchright\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/patchright-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### 📖 推荐工作流（ARIA Snapshot + Ref）\n\n**步骤 1：获取页面快照**\n\n```json\n{ \"type\": \"aria\" }\n```\n\n返回带 `ref` 标识的 ARIA 快照，如：\n```\n[ref=123] button \"登录\"\n[ref=456] textbox \"用户名\"\n```\n\n**步骤 2：基于 ref 交互**\n\n```json\n{\n  \"target\": { \"kind\": \"ref\", \"element\": \"登录按钮\", \"ref\": \"123\" }\n}\n```\n\n**备选：使用 CSS 选择器**\n\n```json\n{\n  \"target\": { \"kind\": \"selector\", \"selector\": \"#login-btn\" }\n}\n```\n\n### 🛠️ 工具一览\n\n#### 核心工具（Playwright MCP 风格）\n\n| 类别 | 工具 |\n|------|------|\n| **导航** | `browser_open`, `browser_navigate`, `browser_navigate_back`, `browser_tabs` |\n| **快照** | `browser_snapshot`（支持 aria/text/html） |\n| **交互** | `browser_click`, `browser_type`, `browser_hover`, `browser_drag`, `browser_select_option`, `browser_press_key` |\n| **表单** | `browser_fill_form`, `browser_file_upload` |\n| **等待** | `browser_wait_for` |\n| **JavaScript** | `browser_evaluate`, `browser_run_code`（需启用） |\n| **截图/PDF** | `browser_take_screenshot`, `browser_pdf_save` |\n| **诊断** | `browser_console_messages`, `browser_network_requests` |\n| **生命周期** | `browser_close`, `browser_install`, `browser_cleanup` |\n| **鼠标** | `browser_mouse_click_xy`, `browser_mouse_move_xy`, `browser_mouse_drag_xy` |\n| **验证** | `browser_verify_element_visible`, `browser_verify_text_visible`, `browser_verify_value` |\n| **追踪** | `browser_start_tracing`, `browser_stop_tracing` |\n\n#### 扩展工具（独有）\n\n| 工具 | 说明 |\n|------|------|\n| `request` | 用浏览器上下文发 HTTP 请求（保留 Cookie），返回 JSON/text |\n| `wait_for_response` | 等待匹配 URL 片段的网络响应并返回 body |\n\n### 🔄 从旧版迁移\n\n旧版 Lite 工具已移除，替换如下：\n\n| 旧工具 | 新工具 |\n|--------|--------|\n| `browse` | `browser_open` 或 `browser_navigate` |\n| `navigate` | `browser_navigate` |\n| `interact` | `browser_click` / `browser_type` / `browser_select_option` |\n| `extract` | `browser_snapshot` / `browser_take_screenshot` |\n| `execute_script` | `browser_evaluate`（或 `browser_run_code`） |\n| `close` | `browser_close` |\n\n### 💾 磁盘占用与清理\n\n临时文件默认目录：\n- **Windows**: `%TEMP%\\patchright-mcp`\n- **Linux/macOS**: `/tmp/patchright-mcp`\n\n包含子目录：\n- `profiles/` - 持久化浏览器 profile\n- `downloads/` - 下载文件\n- `traces/` - 追踪记录\n- `pdfs/` - PDF 导出\n\n**建议**：周期性调用 `browser_cleanup` 清理，注意清理 profiles 会清除登录态。\n\n### ⚙️ 环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `PATCHRIGHT_MCP_CAPS` | 可选能力（逗号分隔：`vision,pdf,testing,tracing`；支持 `all`）。不设置时默认全开 |\n| `PATCHRIGHT_MCP_ENABLE_RUN_CODE=1` | 启用 `browser_run_code`（危险能力，默认关闭） |\n| `PATCHRIGHT_MCP_SECRETS_JSON` | 对输出文本中的敏感信息做掩码（JSON 对象，如 `{\"openai\":\"sk-...\"}`) |\n| `PATCHRIGHT_MCP_SECRETS` | 同上（别名） |\n\n### 📄 License\n\nApache-2.0（见 [LICENSE](LICENSE)）\n\n---\n\n## English\n\nAn MCP (Model Context Protocol) server powered by **Patchright Node.js SDK** (Playwright-compatible with stealth enhancements). Designed for AI agents with comprehensive browser automation capabilities.\n\n### ✨ Key Features\n\n| Feature | Description |\n|---------|-------------|\n| 🎭 **Stealth Browsing** | Based on Patchright, bypasses common anti-bot detection (CDP/Webdriver fingerprints) |\n| 🎯 **ARIA Snapshot + Ref Targeting** | Use `browser_snapshot(type=\"aria\")` to get snapshots with `ref`s for precise element interaction |\n| 🔄 **Session Persistence** | Persistent profiles keep login state by default |\n| 📦 **Structured Responses** | Returns `result/code/tabs/console/downloads/page/snapshot/images` |\n| 🧹 **Disk Hygiene** | `browser_cleanup` cleans temp files to prevent disk bloat |\n| 🌐 **HTTP Extensions** | `request` / `wait_for_response` for browser-context HTTP requests with cookies |\n\n### 📋 Requirements\n\n- **Node.js** 18+\n- **npm** or **pnpm**\n\n### 🚀 Quick Install\n\n```bash\n# Clone repository\ngit clone https://github.com/Frankieli123/patchright-mcp.git\ncd patchright-mcp\n\n# Install dependencies\nnpm ci\n\n# Build project\nnpm run build\n```\n\n**Install browser binaries** (pick one):\n\n```bash\n# Option 1: CLI install\nnpx patchright install chromium\n\n# Option 2: MCP tool (recommended for remote/container environments)\n# Call browser_install tool\n```\n\n### ▶️ Running\n\n```bash\n# Production mode\nnpm start\n\n# Development mode (hot reload)\nnpm run dev\n```\n\n**Optional capabilities** (via `--caps` or env `PATCHRIGHT_MCP_CAPS`):\n\n```bash\n# Enable only vision and pdf\nnpm start -- --caps=vision,pdf\n\n# Enable all capabilities\nnpm start -- --caps=all\n```\n\n### 🔧 Integration\n\n#### Claude Desktop\n\nEdit `claude-desktop-config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"patchright\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/patchright-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### 📖 Recommended Workflow (ARIA Snapshot + Ref)\n\n**Step 1: Get page snapshot**\n\n```json\n{ \"type\": \"aria\" }\n```\n\nReturns ARIA snapshot with `ref` identifiers:\n```\n[ref=123] button \"Login\"\n[ref=456] textbox \"Username\"\n```\n\n**Step 2: Interact using ref**\n\n```json\n{\n  \"target\": { \"kind\": \"ref\", \"element\": \"Login button\", \"ref\": \"123\" }\n}\n```\n\n**Fallback: CSS selector**\n\n```json\n{\n  \"target\": { \"kind\": \"selector\", \"selector\": \"#login-btn\" }\n}\n```\n\n### 🛠️ Tools Overview\n\n#### Core Tools (Playwright MCP Style)\n\n| Category | Tools |\n|----------|-------|\n| **Navigation** | `browser_open`, `browser_navigate`, `browser_navigate_back`, `browser_tabs` |\n| **Snapshot** | `browser_snapshot` (aria/text/html) |\n| **Interaction** | `browser_click`, `browser_type`, `browser_hover`, `browser_drag`, `browser_select_option`, `browser_press_key` |\n| **Forms** | `browser_fill_form`, `browser_file_upload` |\n| **Wait** | `browser_wait_for` |\n| **JavaScript** | `browser_evaluate`, `browser_run_code` (requires enable) |\n| **Screenshot/PDF** | `browser_take_screenshot`, `browser_pdf_save` |\n| **Diagnostics** | `browser_console_messages`, `browser_network_requests` |\n| **Lifecycle** | `browser_close`, `browser_install`, `browser_cleanup` |\n| **Mouse** | `browser_mouse_click_xy`, `browser_mouse_move_xy`, `browser_mouse_drag_xy` |\n| **Verification** | `browser_verify_element_visible`, `browser_verify_text_visible`, `browser_verify_value` |\n| **Tracing** | `browser_start_tracing`, `browser_stop_tracing` |\n\n#### Extension Tools (Unique)\n\n| Tool | Description |\n|------|-------------|\n| `request` | HTTP request using browser context (with cookies), returns JSON/text |\n| `wait_for_response` | Wait for network response matching URL substring and return body |\n\n### 🔄 Migration from Legacy\n\nLegacy Lite tools removed. Replacements:\n\n| Old | New |\n|-----|-----|\n| `browse` | `browser_open` or `browser_navigate` |\n| `navigate` | `browser_navigate` |\n| `interact` | `browser_click` / `browser_type` / `browser_select_option` |\n| `extract` | `browser_snapshot` / `browser_take_screenshot` |\n| `execute_script` | `browser_evaluate` (or `browser_run_code`) |\n| `close` | `browser_close` |\n\n### 💾 Disk Usage & Cleanup\n\nDefault temp directory:\n- **Windows**: `%TEMP%\\patchright-mcp`\n- **Linux/macOS**: `/tmp/patchright-mcp`\n\nSubdirectories: `profiles/`, `downloads/`, `traces/`, `pdfs/`\n\n**Recommendation**: Periodically call `browser_cleanup`. Note: cleaning profiles will clear login state.\n\n### ⚙️ Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `PATCHRIGHT_MCP_CAPS` | Capabilities (comma-separated: `vision,pdf,testing,tracing`; supports `all`). All enabled by default |\n| `PATCHRIGHT_MCP_ENABLE_RUN_CODE=1` | Enable `browser_run_code` (dangerous; disabled by default) |\n| `PATCHRIGHT_MCP_SECRETS_JSON` | Mask sensitive info in output (JSON object, e.g., `{\"openai\":\"sk-...\"}`) |\n| `PATCHRIGHT_MCP_SECRETS` | Same as above (alias) |\n\n### 📄 License\n\nApache-2.0 (see [LICENSE](LICENSE))\n","readmeFilename":"README.md","_rev":"1-6b75965cfc326e7f646a756c76acfc4f"}