Chrome DevTools MCP: Cho Agent AI đôi mắt để nhìn vào trình duyệt

Chrome DevTools MCP: Cho Agent AI đôi mắt để nhìn vào trình duyệt

Hướng dẫn chuyên nghiệp từ cài đặt đến thực chiến: kết nối Chrome DevTools MCP với VS Code, Cursor, GitHub Copilot, Claude Code và Gemini CLI bằng npx chrome-devtools-mcp@latest và cờ --autoConnect. Kèm cấu hình JSON, quy trình kết nối Chrome M144+, ví dụ Lighthouse audit, phân tích lỗi CORS và checklist xác minh hoạt động.

Kỹ thuật
Thẻ (9)
mcp chrome-devtools cursor claude-code github-copilot gemini productivity debugging lighthouse
Mục lục

Tuần trước tôi bảo agent sửa một bug CORS trên trang admin. Nó viết ra ba phiên bản “đúng về mặt lý thuyết” — thêm header, đổi credentials, sửa middleware — không cái nào chạy. Vì nó không thấy request thực tế trong DevTools. Nó chỉ đoán.

Chrome DevTools MCP xóa bỏ khoảng mù đó. Agent mở Chrome thật, đọc Network waterfall thật, chạy Lighthouse thật, rồi mới sửa. Dưới đây là cách tôi cài đặt nó cho VS Code, Cursor, GitHub Copilot, Claude Code và Gemini CLI, kèm những quy trình đã thực sự giúp tôi rút ngắn thời gian debug từ nửa giờ xuống vài phút.

TL;DR — npx chrome-devtools-mcp@latest là lệnh duy nhất bạn cần nhớ. Cờ --autoConnect (Chrome M144+) cho phép tái dùng phiên Chrome đã đăng nhập. Phần còn lại chỉ là dán JSON vào đúng file config.

Nguồn chính thức (đọc trước khi tin tôi)

NguồnLinkDùng khi
GitHub repoChromeDevTools/chrome-devtools-mcpCấu hình client, cờ CLI, danh sách tool
npmchrome-devtools-mcpPhiên bản, changelog
Chrome Developers BlogChrome DevTools (MCP) for your AI agentTriết lý thiết kế
Chrome Developers BlogLet your Coding Agent debug your browser sessionQuy trình --autoConnect
Tool referencedocs/tool-reference.md29 tool có sẵn

Yêu cầu nền tảng: Node.js ≥ 20.19 LTS, Chrome stable (hoặc Chrome for Testing), npm. Dùng --autoConnect cần Chrome M144 trở lên — nếu chưa lên stable, chỉ định --channel=beta hoặc --channel=canary.

Cấu hình chuẩn dùng chung

Gần như tất cả client chia sẻ cùng một cấu hình gốc. Ghim nó lại — mọi biến thể chỉ là thêm cờ:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Cờ -y bỏ qua prompt xác nhận của npx ở lần đầu. @latest bảo đảm client luôn lấy bản mới — đổi lại độ ổn định: pin version ([email protected]) nếu bạn chạy trong CI.

Các cờ tôi dùng nhiều nhất:

CờMục đích
--autoConnectKết nối Chrome M144+ đang chạy — giữ nguyên đăng nhập
--browser-url=http://127.0.0.1:9222Kết nối thủ công qua remote debugging port (sandbox, WSL, VM)
--headlessCI hoặc background task
--isolatedProfile tạm, tự xoá sau phiên — tốt cho audit lặp lại
--channel=betaDùng Chrome Beta khi stable chưa có M144
--viewport=1440x900Chuẩn hoá kích thước khi chụp screenshot
--no-usage-statisticsTắt telemetry Google
--slimChỉ 3 tool (navigate, evaluate, screenshot) — tiết kiệm context

Cài đặt theo từng client

Sáu client dưới đây đều dùng chung cấu hình gốc phía trên — phần khác biệt chỉ là đặt vào đâu và gõ lệnh nào để thêm. Mở phần bạn cần:

1. VS Code + GitHub Copilot

Cách nhanh — cài như plugin (khuyến nghị, gồm cả skills):

  1. Mở Command Palette (⌘⇧P / Ctrl+Shift+P).
  2. Chạy Chat: Install Plugin From Source.
  3. Dán https://github.com/ChromeDevTools/chrome-devtools-mcp.

Cách thủ công — chỉ MCP server:

code --add-mcp '{"name":"chrome-devtools","command":"npx","args":["-y","chrome-devtools-mcp@latest"]}'

Hoặc thêm vào .vscode/mcp.json (workspace) hay user settings:

{
  "servers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Sau đó mở Chat, chọn Agent mode, tick chrome-devtools ở Tools picker.

2. Cursor

One-click: mở nút install trên README.

Thủ công: Cursor Settings → MCP → New MCP Server, dán cấu hình chuẩn phía trên. File kết quả nằm ở ~/.cursor/mcp.json:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect", "--viewport=1440x900"]
    }
  }
}

Restart Cursor. Ở panel Chat bạn sẽ thấy dòng chrome-devtools · 29 tools — đó là tín hiệu xanh.

3. Claude Code

Một dòng CLI (chỉ MCP):

claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest

Plugin đầy đủ (MCP + Skills):

/plugin marketplace add ChromeDevTools/chrome-devtools-mcp
/plugin install chrome-devtools-mcp

Restart Claude Code, chạy /skills để kiểm tra skills đã load. Bản plugin kèm các skill hướng dẫn agent dùng đúng tool — đáng cài nếu bạn muốn độ chính xác cao hơn cấu hình MCP trần.

4. Gemini CLI
# Project-wide — MCP only
gemini mcp add chrome-devtools npx chrome-devtools-mcp@latest

# Toàn máy
gemini mcp add -s user chrome-devtools npx chrome-devtools-mcp@latest

# Hoặc cài dạng extension (MCP + Skills + tự cập nhật)
gemini extensions install --auto-update \
  https://github.com/ChromeDevTools/chrome-devtools-mcp
5. Copilot CLI (GitHub CLI agent)
copilot
/mcp add

Nhập:

  • Server name: chrome-devtools
  • Server Type: [1] Local
  • Command: npx -y chrome-devtools-mcp@latest

Lưu bằng Ctrl+S.

6. Codex CLI (bao gồm Windows 11)
codex mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

Trên Windows 11, sửa .codex/config.toml để Codex tìm đúng Chrome và tăng timeout khởi động:

[mcp_servers.chrome-devtools]
command = "cmd"
args = ["/c", "npx", "-y", "chrome-devtools-mcp@latest"]
env = { SystemRoot = "C:\\Windows", PROGRAMFILES = "C:\\Program Files" }
startup_timeout_ms = 20_000

--autoConnect: kết nối Chrome đã đăng nhập

Đây là chế độ tôi khuyên cho công việc hàng ngày — agent dùng đúng session bạn đang mở: cookie, đăng nhập SSO, extension, tab đang debug. Không phải restart, không phải login lại.

Tóm tắt ba bước: (1) bật chrome://inspect/#remote-debugging trong Chrome M144+, (2) thêm --autoConnect vào args của MCP client, (3) chạy prompt khởi động và bấm Allow trong dialog.

--autoConnect gắn với profile mặc định của Chrome đang chạy. Nếu bạn đa-profile, hãy chắc profile chứa session bạn cần là profile được mở đầu tiên. Agent sẽ thấy mọi window của profile đó — đừng để mở Gmail cá nhân khi đang dùng agent cho khách hàng.

Chi tiết ba bước và cấu hình JSON cho --autoConnect

Bước 1. Trong Chrome (M144+), mở chrome://inspect/#remote-debugging → bật Allow incoming debugging connections. Chrome sẽ ghi token vào user data dir của profile hiện tại.

Bước 2. Thêm --autoConnect vào args. Ví dụ cho Gemini CLI:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--autoConnect"]
    }
  }
}

Nếu stable chưa có M144, thêm --channel=beta (hoặc canary) và đảm bảo Chrome Beta/Canary đã chạy:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--autoConnect", "--channel=beta"]
    }
  }
}

Bước 3. Chạy prompt đầu tiên:

Check the performance of https://developers.chrome.com

Chrome sẽ hiện dialog xin phép — bấm Allow. Từ lúc này agent có thể đọc Network, chạy Lighthouse, và evaluate_script ngay trong tab của bạn.

Khi nào dùng --browser-url thay vì --autoConnect (sandbox, WSL, Docker, VM)

Những môi trường không mở được dialog quyền — chạy Chrome thủ công với cổng debug:

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-profile-stable

Rồi cấu hình client:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  }
}

Chrome yêu cầu --user-data-dir riêng khi bật --remote-debugging-port — đừng dùng profile cá nhân, bất kỳ app nào trên máy đều có thể kết nối vào cổng đó.

29 tool chia theo nhóm

Biết tool nào có sẵn giúp bạn viết prompt gọn hơn và agent chọn đúng.

NhómTool tiêu biểuUse case
Input (9)click, fill_form, hover, press_key, upload_fileReproduce user flow
Navigation (6)navigate_page, new_page, wait_for, list_pagesĐiều hướng SPA
Emulation (2)emulate (device, network, CPU), resize_pageTest 3G, iPhone, reduced-motion
Performance (4)performance_start_trace, performance_analyze_insight, take_memory_snapshotCore Web Vitals, heap growth
Network (2)list_network_requests, get_network_requestLọc CORS, payload, timing
Debugging (6)lighthouse_audit, evaluate_script, list_console_messages, take_screenshot, take_snapshotAudit, console, DOM tree

Cần tiết kiệm context? Dùng --slim — chỉ 3 tool navigate_page, evaluate_script, take_screenshot.

Prompt mẫu đã dùng thật

Lighthouse audit có hướng dẫn

Đừng chỉ nói “chạy Lighthouse”. Hãy đưa ngưỡng và yêu cầu kế hoạch:

Truy cập http://localhost:3000/pricing. Emulate 4G throttling + Moto G4.
Chạy lighthouse_audit với các category performance, accessibility, seo.
Nếu LCP > 2.5s hoặc CLS > 0.1, mở performance_start_trace, reload trang,
stop trace, rồi dùng performance_analyze_insight để trả về top 3 nguyên
nhân. Đề xuất fix cụ thể kèm file/line trong repo hiện tại, không sửa code.

Prompt này buộc agent lập plan trước, và không edit code trong vòng đầu — bạn review insight trước khi cho sửa.

Debug CORS (ví dụ cổ điển)

Mở https://app.local/dashboard. Đợi mạng idle. Dùng list_network_requests
lọc status >= 400 hoặc failed, chỉ domain api.local.
Với request lỗi đầu tiên, gọi get_network_request để đọc request & response
headers đầy đủ. Đối chiếu Access-Control-Allow-Origin với Origin, kiểm tra
preflight OPTIONS có trả 204 không, và xem có thiếu Allow-Credentials khi
client gửi credentials: 'include' không. Tóm tắt root cause trong 3 gạch
đầu dòng và đề xuất patch ở server middleware — không sửa code.

Ba điểm hay gặp mà agent sẽ bỏ sót nếu không được gợi ý: (1) preflight thiếu Access-Control-Allow-Methods, (2) Allow-Origin: * không tương thích credentials: 'include', (3) proxy (Nginx/Cloudflare) strip header ở layer khác.

Reproduce bug form + console trace

navigate_page tới /checkout. fill_form với {email:"[email protected]", card:"4242..."},
click "Place order". wait_for text "Order confirmed" hoặc timeout 10s.
Nếu timeout: list_console_messages (level error, warning),
list_network_requests (status >= 400), take_screenshot viewport.
Trả về bundle: console log + failing request + screenshot + giả thuyết
nguyên nhân.

Performance regression giữa hai commit

Emulate Slow 4G. Trace 2 lần: trước và sau khi checkout commit abc123.
So sánh LCP, TBT, JS bundle size từ network. Báo delta và flag nếu
TBT tăng > 100ms.

Checklist xác minh hoạt động

Sau khi dán JSON, chạy lần lượt:

  • npx chrome-devtools-mcp@<pinned-version> --help chạy được (Node ≥ 20.19; dùng phiên bản cụ thể đã review, không dùng @latest trên máy công ty)
  • Restart client — thấy chrome-devtools trong tool picker
  • Prompt khởi động: “Check the performance of https://developers.chrome.com” → Chrome tự mở
  • Dialog chrome://inspect hiện khi dùng --autoConnect — bấm Allow
  • Agent trả về Lighthouse scores, không phải “tôi không thể truy cập trình duyệt”
  • list_network_requests trả về > 0 request cho trang public
  • take_screenshot tạo file PNG (kiểm tra attachments trong chat)
  • Nếu lỗi ECONNREFUSED với --browser-url: Chrome đang chạy cổng đúng? curl http://127.0.0.1:9222/json/version phải trả JSON
  • Nếu --autoConnect không kết nối được: Chrome version ≥ 144 (chrome://version)? Đã bật Allow trong chrome://inspect?
  • Log debug: thêm --logFile=/tmp/cdp-mcp.log và DEBUG=* khi báo bug

Trên macOS, nếu Chrome khởi động chậm và Codex/Cursor timeout, tăng startup_timeout_ms trong config (mặc định 10s, thử 20–30s). Lần đầu npx cũng tốn 5–15s để fetch package về ~/.npm/_npx.

Bảo mật: đừng bỏ qua phần này

Chrome DevTools MCP phơi toàn bộ nội dung trình duyệt cho MCP client. Agent đọc được DOM, cookie, localStorage, network payload. Một số hệ quả thực tế:

  • Không đăng nhập tài khoản cá nhân vào profile bạn dùng với agent. Dùng profile công việc riêng, hoặc --isolated.
  • Redact headers nhạy cảm: --redactNetworkHeaders che Authorization, Cookie, Set-Cookie trước khi gửi về client.
  • --remote-debugging-port là public local port: mọi process trên máy đều connect được. Đừng bật khi đang browse bank.
  • Tắt telemetry nếu cần: --no-usage-statistics hoặc env CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1. CI tự động tắt nếu CI env được set.
  • Pin version trong CI: [email protected] thay vì @latest để tránh supply-chain surprise. Tham khảo OWASP MCP Top 10 về tool description poisoning.

Hướng dẫn dùng trong doanh nghiệp (enterprise guardrails)

Nếu tổ chức của bạn qua security review cho Chrome DevTools MCP, thường sẽ có một bộ điều kiện bắt buộc đi kèm. Bản dưới đây gom những ràng buộc hay gặp nhất — khớp với phần trên nhưng cụ thể và cứng hơn.

Cấu hình bắt buộc (tắt telemetry, pin version)

Thay thế cấu hình mặc định @latest trong các ví dụ phía trên bằng bản này khi chạy trên máy công ty:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@<pinned-version>",
        "--no-usage-statistics",
        "--no-performance-crux"
      ]
    }
  }
}

Hai cờ --no-usage-statistics và --no-performance-crux tắt hai kênh gửi dữ liệu riêng biệt về Google: chỉ số sử dụng tool, và URL trang trong performance trace gửi đến CrUX API. Không có chúng, cả usage metadata lẫn URL nội bộ đều có thể rò ra.

Điều kiện sử dụng

  1. Chỉ máy dev cá nhân. Không chạy trên shared host, bastion, remote dev workspace, hay CI/CD. Tức là bỏ luôn ý tưởng nhúng vào pipeline ở phần productivity — giữ nó chạy tay trên laptop.
  2. Chỉ non-production. Dùng cho local dev và testing; không trỏ agent vào URL production, API production, hay tài khoản khách hàng thật.
  3. Tắt telemetry: luôn có --no-usage-statistics và --no-performance-crux.
  4. Profile Chrome biệt lập. Mặc định server dùng ~/.cache/chrome-devtools-mcp/chrome-profile — không đụng vào Chrome cá nhân. Cần cô lập sâu hơn thì thêm --isolated (profile tạm, tự xoá sau phiên). Tránh --autoConnect với profile chứa credentials production.
  5. Pin version, chạy npm audit. Không dùng @latest. Ghim về version cụ thể đã review, và chạy npm audit trước khi nâng.
  6. Giữ prompt xin phép trong Claude Code. Mutating action (click, fill, navigate_page, evaluate_script, …) phải hỏi approval trước khi chạy. Read-only (list_pages, get_console_message, list_network_requests) có thể auto-approve. Không tắt permission prompt.

Nếu tổ chức của bạn chưa có security review chính thức, coi sáu điều trên như baseline tối thiểu trước khi cho agent đụng bất kỳ codebase nào khác laptop cá nhân của bạn. Đặc biệt: điều 1 (không CI) mâu thuẫn có chủ ý với “Performance budget enforcement trong CI” ở section tiếp theo — đó là workflow cá nhân tôi dùng, không phải khuyến nghị cho repo chung của công ty.

Tăng productivity — từ workflow của tôi

Một số cách tôi dùng Chrome DevTools MCP để rút ngắn thời gian xử lý công việc, sau vài tuần dùng thật:

1. PR review “visual-first”. Thay vì pull branch về máy, tôi bảo agent mở preview URL (Vercel/Netlify), chạy Lighthouse trên 3 trang chính, so sánh với baseline trên main. Agent trả về regression report — thường phát hiện bundle tăng 40KB trước khi con người nhận ra.

2. Debug flaky E2E. Test Playwright fail ngắt quãng? Bảo agent mở URL staging, replay đúng flow trong test đó, capture console + network, đối chiếu với CI log. Tỷ lệ tìm ra root cause (race condition, third-party timeout, cookie khác domain) cao hơn hẳn so với đọc trace file thô.

3. Migration audit. Migrate từ Webpack sang Vite, hoặc upgrade framework major. Snapshot performance trên 10 URL quan trọng trước migrate, chạy lại sau, diff metrics. Agent tự viết bảng so sánh.

4. Bug reproduction “hands-free”. Khách hàng báo lỗi với mô tả mơ hồ? Thả URL + step vào chat, agent reproduce, capture screenshot + console, tạo issue có đủ ngữ cảnh. Tôi rút thời gian từ “20 phút lăn tăn mở DevTools” xuống 3 phút.

5. Accessibility sweep. Chạy lighthouse_audit với category accessibility + take_snapshot DOM, yêu cầu agent list các violation WCAG A/AA kèm CSS selector. Dùng làm backlog cho sprint a11y.

6. Performance budget enforcement trong CI. Kết hợp --headless --isolated trong pipeline, fail build nếu LCP > budget. Rẻ hơn đăng ký SaaS Lighthouse CI và tích hợp với agent review PR cùng lúc.

Con số thật từ tuần trước: 1 PR regression LCP 400ms bị bắt trước merge; 2 bug CORS fix trung bình 5 phút thay vì 25; 1 flaky test thành deterministic sau khi agent chỉ ra race condition ở navigator.serviceWorker.ready. Không phải magic — chỉ là agent cuối cùng thấy được cái nó đang sửa.

Bảy pattern ứng dụng thực tế (tham chiếu rộng hơn)

Sáu workflow phía trên là của riêng tôi. Chrome Developers liệt kê thêm một bộ pattern chuẩn mà các team đã áp dụng thành công — đáng ghi vào backlog khi bạn tìm điểm đưa MCP vào quy trình mới:

PatternAgent làm gìTool chính
Automated bug fixingThấy lỗi runtime trực tiếp, sửa, rồi test lại ngay trong tab đã reproduce — không dựa vào mô tả gián tiếplist_console_messages, evaluate_script, navigate_page
Persistent stylingĐưa CSS tinker trong DevTools inspector trở lại source code — giải quyết cảnh “chỉnh xong refresh là mất”take_snapshot, evaluate_script, editor
Performance optimizationPhân tích site performance với real data, khớp Core Web Vitals với nguyên nhân cụ thểperformance_start_trace, performance_analyze_insight, lighthouse_audit
Automated UI/UX testingKiểm chứng tính năng chạy đúng kỳ vọng qua flow thật, không giả lậpfill_form, click, wait_for, take_screenshot
Visual verificationNhìn layout thật, bắt visual bug (overflow, dark-mode contrast, responsive break) — không chỉ đọc HTMLtake_screenshot, emulate
Security scanningScan vulnerability với full context của network + DOM — XSS sink, mixed content, cookie flag thiếulist_network_requests, get_network_request, take_snapshot
Reverse engineeringInspect traffic real-time của site bên ngoài để tự động sinh API client hoặc SDK wrapperlist_network_requests, get_network_request, evaluate_script

Hai pattern ít được nói tới mà cá nhân tôi thấy thú vị: persistent styling — agent lấy giá trị hex, spacing, radius bạn tweak trong DevTools rồi tự commit vào đúng @theme hoặc token file trong source — và reverse engineering để viết client SDK, đặc biệt hữu ích khi tích hợp SaaS chỉ có portal UI mà không public API docs.

Nguồn: Chrome for Developers — Chrome DevTools MCP for your AI agent và Let your Coding Agent debug your browser session.

Kết: cho agent đôi mắt, giữ cho mình tay lái

Chrome DevTools MCP không thay thế kỹ năng debug của bạn. Nó xóa khoảng trễ giữa “agent đoán” và “agent kiểm chứng”. Cài một lần, đặt hai cờ --autoConnect với --viewport, viết prompt buộc agent plan-rồi-mới-fix — và mỗi ngày bạn lấy lại vài mươi phút vốn rót vào F12 + reload + nheo mắt vào Network panel.

Tool tham khảo, prompt mẫu, checklist — tất cả ở trên. Phần khó nhất còn lại: xoá thói quen viết prompt kiểu “fix CORS” và thay bằng prompt có ngữ cảnh cụ thể. Agent càng thấy rõ, bạn càng ít phải kèm.

Luồng

0
⌘/Ctrl+Enter để gửiGõ / để xem lệnh · Tab để @nhắc tên
← Quay lại