cdp-mcp
Controls Google Chrome through the Chrome DevTools Protocol for browser automation and visual verification, including screenshots, DOM element inspection, form input and click interactions, and CSS selector-based pixel-perfect clipping.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cdp-mcp take a screenshot of the #login-form and verify it's visible"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📸 cdp-mcp
Zero-Dependency, High-Precision Chrome DevTools Protocol (CDP) MCP Server
專為真實瀏覽器視覺驗收、UI 跑版檢測與極速自動化打造的原子化 MCP 伺服器
⭐️ 喜歡這個專案嗎?歡迎在 GitHub 點個 Star!
如果 cdp-mcp 幫助您的 AI Agent 解決了截圖跑版或龐大依賴的困擾,請不要吝嗇為我們點亮一顆右上角的 ⭐️ Star!
您的支持是持續維護與推動零依賴開源生態的最大動力。
💡 Why cdp-mcp? (為什麼選擇 cdp-mcp?)
在當前的 AI Agent 與自動化領域中,網頁視覺驗收面臨著嚴重的「兩極化困境」:
官方派 (Playwright / Puppeteer MCP):動輒下載 300MB+ 的獨立 Chromium 核心,記憶體開銷大、啟動遲緩,嚴重浪費磁碟與資源。
開源 CDP 派 (如 undetectable-io、cdp-browser-mcp):
❌ 無法全自動接管:要求使用者必須手動提前開好 Chrome,並手動傳入
--remote-debugging-port=9222。❌ Token 瘋狂浪費:提供多達 25 個細碎的底層工具(如 NewTarget, Connect, PageEnable, DOMGetDocument),一個簡單的截圖需與 LLM 來回往返 8 輪,狂吃 20,000+ Tokens!
❌ 現代前端狀態阻攔:使用傳統
.value = ...賦值會直接被 React 19、Vue 的受控組件(Controlled Components)虛擬 DOM 丟棄。
🌟 cdp-mcp 的顛覆性解法:
🚀 極致零依賴 (Zero Dependency):徹底拋棄動輒數百 MB 的 Puppeteer/Playwright,僅依賴 Node.js 原生
WebSocket與系統既有 Chrome/Edge。🔍 全自動跨平台探測:免手動開瀏覽器!自動尋找本機 Chrome / Edge,啟動獨立 Temp Profile 沙盒,任務結束自動秒殺釋放記憶體。
⚡️ 高階原子複合操作 (One-Shot Action):將「導航 + 表單注入 + 點擊展開 + 局部裁切」收斂為單一工具呼叫,1 輪往返、僅耗費 ~1.5k Tokens。
🧬 React 19 / Vue 原生描述符穿透:內建
HTMLInputElement.prototypeSetter 劫持技術,100% 穿透 React/Vue 受控表單。📐 CSS Selector 像素級無損裁切:透過 Chrome 渲染管線直接在物理邊界裁切 PNG,絕不產生縮放模糊。
Related MCP server: bwb-browser
🏛️ Architecture (系統架構)
flowchart TD
subgraph Agentic_Layer ["🤖 AI Agent 環境 (Claude Desktop / Antigravity / Cursor)"]
Agent["AI Assistant / Verifier Agent"]
end
subgraph MCP_Boundary ["⚡ cdp-mcp 核心伺服器 (Node.js 24)"]
Server["MCP Server (Stdio Transport)"]
AutoDetect["Browser Auto-Detector\n(Win / macOS / Linux)"]
CDPClient["Native WebSocket CDP Client"]
Injector["React 19 / Vue Setter Injector"]
Clipper["DOM BoundingRect Clip Engine"]
LifeCycle["Sandbox & Lifecycle Guard\n(--user-data-dir Cleanup)"]
end
subgraph System_Browser ["🌐 系統原生瀏覽器 (零額外下載)"]
Chrome["Google Chrome / Microsoft Edge"]
Render["Chrome DevTools Protocol (CDP)\nPage / DOM / Emulation / Input"]
end
Agent -->|"MCP Call (take_screenshot)"| Server
Server --> AutoDetect
AutoDetect -->|"Spawn with Temp Profile"| Chrome
Server --> CDPClient
CDPClient -->|"ws://localhost:PORT/devtools/page"| Render
Render --> Injector
Injector --> Clipper
Clipper -->|"Pixel-Perfect PNG"| Agent
Server --> LifeCycle
LifeCycle -.->|"Auto Kill & Cleanup on Exit"| Chrome📊 市面主流 CDP 解決方案橫向對比
我們對市面上主流方案進行了全維度的深度實測(包含 2026 最新開源專案與具備 25 款工具的重型方案):
評估維度 | 官方派 (Playwright MCP) | 開源 CDP 派 (cdp-browser-mcp 等) | 重型控制派 (chromium-cdp-mcp) | 🌟 cdp-mcp (本專案) |
外部套件體積 | ❌ 300MB+ Chromium | 🟡 中等 (依賴第三方驅動) | 🟢 輕量 (原生 WebSocket) | 🟢 極致輕量 (0 下載,系統原生) |
瀏覽器生命週期 | 啟動慢,常駐耗能 | ❌ 需手動提前開瀏覽器 | ❌ 需手動開瀏覽器且必傳 Port | 🟢 全自動探測啟動、用完自動秒殺 |
呼叫原子化程度 | 多步驟來回 | 多步驟來回 | ❌ 25 個細碎 Tool (來回 8 輪) | 🟢 高階複合一步到位 (1 輪完成) |
React 19 / Vue 穿透 | 框架級模擬 | ❌ 無 (普通 .value= 易失效) | ❌ 無 (Input.insertText 易丟事件) | 🟢 原生 Setter 描述符注入,100% 穿透 |
DOM 局部無損裁切 | 需手動計算座標 | ❌ 僅 Viewport/FullPage | ❌ 僅 Viewport/FullPage | 🟢 CSS Selector 像素級無損裁切 |
Token 消耗效率 | 🔴 消耗較高 | 🟡 中等 (~5k tokens) | 🔴 8 輪往返 (~20k tokens) | 🟢 單次原子呼叫 (~1.5k tokens) |
開源憑證 | Apache-2.0 | MIT License | MIT License | 🛡️ Apache-2.0 (專利防衛) |
📚 深入評估白皮書:
🌐 多方案全景橫向評估白皮書:五大派系在 Token、內存、並發與現代 Web 兼容性深度對決。
🥊 1v1 單挑深度對照報告:針對 undetectable-io 25 款細碎工具的原子化對照。
🚀 Quick Start (快速開始)
1. 安裝與建置
# Clone 本專案
git clone https://github.com/xx8897/cdp-mcp.git
cd cdp-mcp
# 安裝輕量依賴並編譯 TypeScript
npm install
npm run build2. 在 AI 編輯器 / 工具中配置
🔹 Antigravity / Cursor / VS Code (mcp_config.json)
{
"mcpServers": {
"cdp-mcp": {
"command": "node",
"args": ["<PATH_TO_PROJECT>/dist/index.js"]
}
}
}🔹 Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"cdp-mcp": {
"command": "node",
"args": ["D:/codespace/projects/cdp-mcp/dist/index.js"]
}
}
}3. 執行自我驗證測試
node tests/test-mcp.js測試通過後會在 tests/output/ 目錄產生 test_sample.png,即代表 CDP 管道與截圖裁切運作完全正常!
🦾 Tools Specification (MCP 工具詳細規格)
1. take_screenshot
對目標網址進行全景視口截圖或精準的 DOM 局部元素裁切。
{
"name": "take_screenshot",
"arguments": {
"url": "http://localhost:3000/dashboard",
"outputPath": "d:/output/dashboard_card.png",
"selector": ".analytics-card-primary",
"waitFor": ".chart-rendered",
"delay": 1500,
"width": 1920,
"height": 1080,
"dpr": 2
}
}2. interact_and_screenshot
先自動完成表單輸入(穿透 React 19 虛擬 DOM)與點擊動作,再執行精準裁切截圖。
{
"name": "interact_and_screenshot",
"arguments": {
"url": "http://localhost:3000/login",
"outputPath": "d:/output/logged_in_state.png",
"inputSelector": "#user-email",
"inputValue": "admin@example.com",
"clickSelector": "button[type='submit']",
"waitFor": ".welcome-banner",
"delay": 1000
}
}3. inspect_element
檢測指定 DOM 元素在瀏覽器視口中的真實物理邊界盒(Bounding Box)與可見性,專門用於偵測跑版與元素重疊。
{
"name": "inspect_element",
"arguments": {
"url": "http://localhost:3000",
"selector": "#submit-btn"
}
}回傳範例:
{
"success": true,
"found": true,
"isVisible": true,
"rect": { "x": 120, "y": 450, "width": 200, "height": 48 }
}🤖 Visual Verifier Agent (專屬驗收特工)
本專案附帶專用特工架構:
核心使命:前端 UI 實機驗收、跑版比對與視覺審查。
安全沙盒 (Read-Only Safety):特工僅被授權使用
mcp__cdp-mcp__*與read_file,在物理層面剝奪代碼寫入權限,保證「專職驗收、絕對無法擅自改動業務代碼」。
📄 License & Attribution (授權與署名條款)
本專案採用 Apache License 2.0 授權開源,並隨附官方 NOTICE 聲明文件。
Copyright 2026 xx8897 and cdp-mcp contributors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0🛡️ 專利防禦與商用保障
寬鬆商用:允許個人、團隊或企業自由修改、整合與商業發布。
專利反訴防禦條款:任何使用或參與本專案者均獲得免費專利授權;若有任何實體向本專案提出專利侵權訴訟,其專利授權將立即自動終止,保障獨立開源開發者免於專利蟑螂威脅。
NOTICE 強制展示義務(第 4(d) 條):任何包含或分發本專案(或衍生作品)的商業產品,必須在軟體版權聲明、說明文件或界面中,完整保留並展示 NOTICE 文件中載明之原創作者姓名與 GitHub 來源連結。
修改標記義務(第 4(b) 條):依據第 4(b) 條,任何修改過本專案原始碼者,需在修改檔案中標註改動說明。
🌟 喜歡這個專案嗎?
如果您認同 Zero-Dependency 與 原子化高效率 AI Agent 的開發理念,請在 GitHub 為我們點上一顆 Star ⭐️!
給予 Star 支持 • 提交 Issue 建議 • 查看評測白皮書
Made with ❤️ by xx8897 and open-source contributors.
Available Tools
3 toolsinspect_elementB
Inspect a DOM element on a webpage via CDP: check if it exists, its computed physical bounding box (x, y, width, height), and whether it is currently visible.
Inputs: url (required), selector (required), delay, width, +2 more.
interact_and_screenshotB
Simulate user input (with React/Vue controlled component penetration) and/or button click on a webpage, then capture a screenshot.
Inputs: url (required), outputPath (required), dpr, delay, +7 more.
take_screenshotB
Capture a pixel-perfect fullpage or element-level screenshot of a webpage using real Chrome/Edge CDP without Puppeteer/Playwright dependencies.
Inputs: url (required), outputPath (required), dpr, delay, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
take_screenshot and interact_and_screenshot overlap since the latter is essentially a superset that also produces a screenshot, so an agent may be unsure whether to use the simpler tool or always reach for the interactive one. inspect_element is clearly distinct, and the descriptions do help clarify the intent boundary.
All names are snake_case and start with an action verb (take_, interact_, inspect_), which is mostly consistent. interact_and_screenshot deviates slightly by embedding a conjunction and a compound verb phrase rather than a clean verb_noun form.
Three tightly scoped tools is on the lean side but each earns its place for a focused CDP screenshot/inspection server. It stays well under the point where a small surface would feel arbitrary or padding-driven.
The surface covers capture, interaction, and element inspection, but notable gaps remain: no explicit navigation/URL loading tool, no wait-for-selector or network-idle readiness control, and no way to retrieve console/network diagnostics or script evaluation. Agents will hit dead ends for common flows like waiting for dynamic content before capturing.
Related MCP Connectors
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Hosted real Google Chrome MCP with per-user persistent state. Navigate, click, type, screenshot.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenancesingle-binary MCP server that gives AI agents a browser. 66 tools for navigation, form filling, data extraction, screenshots, and DOM diffing — built on pure Chrome DevTools Protocol.14MIT
- AlicenseAqualityBmaintenanceA lightweight 30KB MCP browser automation server that uses raw Chrome DevTools Protocol to enable AI agents to browse the web, take screenshots, interact with elements, and capture live page events like console logs and network requests.41108 npm20MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to drive a real Chrome instance over the Chrome DevTools Protocol — opening and navigating tabs, reading compact YAML page outlines with refs, clicking, typing, scrolling, screenshotting, and evaluating scripts — with no browser extension or installed dependencies. It also audits pages for horizontal overflow and WCAG AA contrast, available both as an MCP tool and as a CI-friendly CLI.15 npmMIT
- AlicenseNot gradedqualityAmaintenanceA local MCP server that lets AI coding tools drive the user's actual, already-logged-in Chrome browser — snapshotting pages, clicking, typing, navigating, reading content, taking screenshots, and inspecting cookies, network traffic, and console output. Browser automation happens through a Chrome extension using Native Messaging, so no remote-debugging port is exposed and all communication stays on the local machine.1 npmISC