# playwright-mcp: cho AI tự điều khiển trình duyệt — hướng dẫn cài đặt và dùng

> playwright-mcp là một MCP server do Microsoft phát hành. Nó cho phép trợ lý AI (Claude Code, Cursor, VS Code Copilot…) mở trình duyệt và thao tác trên trang web bằng cây truy cập (accessibility tree) của Playwright. Cài khá dễ: chỉ cần Node.js 18 trở lên và thêm một đoạn cấu hình hoặc một dòng lệnh vào ứng dụng AI của bạn.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-03 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/playwright-mcp-ai-dieu-khien-trinh-duyet-huong-dan-cai-dat-2

Playwright MCP là một máy chủ MCP (Model Context Protocol) do Microsoft phát hành, giúp trợ lý AI điều khiển trình duyệt web thông qua Playwright. Hiểu đơn giản: bạn nói với AI "vào trang này, tìm giúp mình cái kia", AI sẽ tự mở trình duyệt, bấm, gõ, đọc nội dung rồi báo lại cho bạn.

Repo hợp với ba nhóm người. Thứ nhất là dân văn phòng, chủ shop muốn giao cho AI những việc lặp đi lặp lại trên web. Thứ hai là lập trình viên mới muốn AI tự kiểm tra giao diện web mình vừa viết. Thứ ba là người đã dùng Claude Code, Cursor hay VS Code và muốn AI có thêm "đôi tay" để thao tác trên trình duyệt. Repo hiện có khoảng 39.570 sao và 3.427 fork, giấy phép Apache-2.0, vẫn được cập nhật trong vài tháng gần đây.

Điểm đáng giá nhất là cách nó "nhìn" trang web. Thay vì chụp ảnh màn hình rồi nhờ mô hình đoán chỗ cần bấm, nó đưa cho AI cấu trúc trang dưới dạng văn bản có tổ chức. Nhờ vậy AI không cần mô hình xử lý ảnh, thao tác chính xác hơn và ít "bấm nhầm" hơn.

```repo
- repo | microsoft/playwright-mcp
- kind | MCP server
- desc | Máy chủ MCP của Microsoft cho phép AI mở, đọc và thao tác trên trang web qua Playwright, không cần ảnh chụp màn hình.
- stars | 40k
- lang | TypeScript
- license | Apache-2.0
```

## Playwright MCP làm được gì

### Đọc trang web bằng cấu trúc, không bằng ảnh

Server dùng accessibility tree của Playwright, tức là danh sách các nút, ô nhập, đường dẫn, tiêu đề… của trang. Lợi ích thực tế: mô hình AI nào cũng dùng được, kể cả mô hình không biết đọc ảnh. Việc AI chọn đúng nút nào cũng bớt mơ hồ hơn so với kiểu nhìn ảnh rồi đoán.

### Chạy được với rất nhiều ứng dụng AI

README hướng dẫn cho nhiều công cụ: VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Codex, Gemini CLI, Goose, Grok, Junie, Kiro, LM Studio, opencode, Warp, Cline, Copilot, Amp, Antigravity, Factory, Qodo Gen… Bạn dùng công cụ nào thì cũng có đường cài, phần lớn chỉ là dán một đoạn cấu hình giống nhau.

### Tùy chỉnh bằng tham số

Bạn đưa tham số vào danh sách `args` trong cấu hình. Vài tham số có ích với người mới:

- `--headless`: chạy trình duyệt ẩn. Mặc định trình duyệt hiện ra cửa sổ để bạn xem AI làm.
- `--browser`: chọn trình duyệt, gồm chrome, firefox, webkit, msedge.
- `--isolated`: giữ hồ sơ trình duyệt trong bộ nhớ, không lưu xuống đĩa. Hợp khi bạn không muốn lưu lại đăng nhập hay cookie.
- `--device` và `--mobile`: giả lập điện thoại. README nói trang bản di động thường nhẹ hơn nên tiết kiệm token.
- `--caps`: bật thêm khả năng như vision, pdf, devtools.
- `--extension`: kết nối vào trình duyệt đang mở sẵn (chỉ Edge/Chrome, cần cài tiện ích "Playwright Extension").
- `--output-dir`: chọn thư mục lưu các tệp tự đặt tên, ví dụ ảnh chụp màn hình.

Mỗi tham số còn có biến môi trường tương ứng, ví dụ `PLAYWRIGHT_MCP_HEADLESS` hay `PLAYWRIGHT_MCP_BROWSER`. README còn liệt kê thêm nhiều tùy chọn khác (kết nối CDP, chặn service worker, giới hạn origin…), bạn xem danh sách đầy đủ trong README của repo.

### Giới hạn truy cập tệp để an toàn hơn

Mặc định server chỉ cho truy cập tệp trong thư mục làm việc (workspace) và chặn các địa chỉ `file://`. Muốn mở rộng thì phải bật `--allow-unrestricted-file-access` một cách chủ động.

## Cần chuẩn bị gì

Theo tư liệu, bạn chỉ cần hai thứ:

- Node.js 18 trở lên (package.json cũng yêu cầu Node >=18).
- Một ứng dụng khách MCP (MCP client) như VS Code, Cursor, Windsurf, Claude Desktop, Goose, Grok, Junie hoặc công cụ nào hỗ trợ MCP.

README không nói cần API key riêng cho chính Playwright MCP, cũng không nêu yêu cầu GPU hay hệ điều hành cụ thể. Tất nhiên ứng dụng AI bạn dùng có thể cần tài khoản hay key của nó, việc đó nằm ngoài repo này.

Cách kiểm tra Node.js nhanh: mở terminal (PowerShell trên Windows, Terminal trên macOS) và gõ `node --version`. Ra số 18 trở lên là đủ.

## Cài đặt từng bước

```steps
- Kiểm tra Node.js | Chạy node --version, cần từ 18 trở lên
- Chọn ứng dụng AI | Xác định bạn dùng Claude Code, VS Code, Cursor, Codex…
- Thêm server | Dán cấu hình chuẩn hoặc chạy lệnh add của ứng dụng đó
- Khởi động lại | Mở lại ứng dụng để nó nhận MCP server mới
- Thử một yêu cầu | Nhờ AI mở một trang web đơn giản
```

### Bước 1: Kiểm tra Node.js

Mở terminal và gõ lệnh dưới. Nếu báo "không tìm thấy lệnh" thì bạn chưa cài Node.js, hãy cài bản 18 trở lên trước.

```bash
node --version
```

### Bước 2: Dùng cấu hình chuẩn (cách chung nhất)

Phần lớn công cụ nhận cùng một đoạn cấu hình. README gọi đây là "standard config". Bạn dán đoạn này vào file cấu hình MCP của ứng dụng (hoặc ô "Add MCP server" nếu có):

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}
```

`npx` là lệnh đi kèm Node.js, nó tự tải và chạy gói `@playwright/mcp` mỗi khi cần, nên bạn không phải cài riêng. Phần `@latest` nghĩa là luôn dùng bản mới nhất.

### Bước 3: Hoặc dùng lệnh riêng của từng công cụ

Nếu ứng dụng của bạn có lệnh thêm MCP, đây là các lệnh README ghi. Bạn chỉ chọn một dòng hợp với công cụ mình đang dùng.

Claude Code:

```bash
claude mcp add playwright npx @playwright/mcp@latest
```

Codex:

```bash
codex mcp add playwright npx "@playwright/mcp@latest"
```

VS Code (chạy trong terminal, lệnh này thêm server vào VS Code):

```bash
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
```

Grok:

```bash
grok mcp add playwright -- npx @playwright/mcp@latest
```

Amp:

```bash
amp mcp add playwright -- npx @playwright/mcp@latest
```

Factory:

```bash
droid mcp add playwright "npx @playwright/mcp@latest"
```

Với Cursor, README hướng dẫn vào `Cursor Settings` → `MCP` → `Add new MCP Server`, đặt tên tùy ý, chọn kiểu `command` và nhập `npx @playwright/mcp@latest`. Với Goose, vào `Advanced settings` → `Extensions` → `Add custom extension`, chọn kiểu `STDIO` và đặt command là `npx @playwright/mcp`. Với Claude Desktop, Windsurf, Gemini CLI, README bảo dùng cấu hình chuẩn ở Bước 2 theo hướng dẫn MCP của từng công cụ.

Với Codex, bạn cũng có thể sửa file `~/.codex/config.toml`:

```toml
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
```

### Bước 4: Thêm tham số nếu cần

Muốn chạy trình duyệt ẩn, bạn thêm tham số vào `args`. Ví dụ dưới là cách sắp xếp theo đúng kiểu README mô tả (tham số nằm trong danh sách `args`):

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless"
      ]
    }
  }
}
```

```note
Mặc định trình duyệt hiện cửa sổ thật. Nếu bạn dùng --extension để nối vào trình duyệt đang mở sẵn, AI có thể thao tác trên các trang bạn đã đăng nhập. Hãy cân nhắc kỹ trước khi cho phép, và đừng giao việc liên quan tiền bạc hay dữ liệu nhạy cảm khi chưa kiểm soát được AI làm gì.
```

### Bước 5: Khởi động lại ứng dụng

Sau khi thêm cấu hình, hãy đóng và mở lại ứng dụng AI. Nhiều công cụ chỉ nạp danh sách MCP server lúc khởi động. Vấp phổ biến nhất của người mới là dán cấu hình xong mà không khởi động lại, rồi tưởng không chạy.

## Kiểm tra đã chạy được chưa

README không có phần "kiểm tra" riêng, nên mình gợi ý cách thử đơn giản, dựa trên hành vi mặc định mà tư liệu nêu:

1. Trong ứng dụng AI, mở danh sách MCP server (tên mục tùy công cụ, thường nằm trong phần Settings hoặc lệnh `/mcp`). Bạn sẽ thấy một server tên `playwright`.
2. Gõ một yêu cầu đơn giản, ví dụ: "Dùng trình duyệt mở trang https://example.com và cho mình biết tiêu đề trang".
3. Vì mặc định trình duyệt chạy dạng có cửa sổ (không headless), bạn sẽ thấy một cửa sổ trình duyệt bật lên. AI sau đó báo lại nội dung trang.

Lần chạy đầu có thể hơi chậm vì `npx` phải tải gói về. Nếu thành công, bạn đã sẵn sàng.

## Dùng vào việc thật

### Chủ shop theo dõi giá đối thủ

Bạn bán hàng online và muốn biết đối thủ đang bán một sản phẩm giá bao nhiêu. Bạn nhập câu lệnh như sau:

```text
Mở trang sản phẩm này, đọc tên, giá hiện tại và tình trạng còn hàng, rồi tóm tắt thành bảng ngắn cho mình.
```

AI mở trang, đọc cấu trúc và trả lại thông tin. Bạn dán thêm vài đường dẫn là có bảng so sánh để tham khảo. Việc này vẫn cần bạn kiểm tra lại số liệu, vì AI có thể đọc sai khi trang thay đổi giao diện.

> Cho AI một đôi tay thao tác trên trình duyệt, bạn chỉ còn việc nói rõ mình muốn gì.
>
> — Ông T

### Nhân viên văn phòng điền biểu mẫu lặp lại

Bạn phải nhập cùng một kiểu thông tin lên một cổng web nội bộ nhiều lần. Bạn có thể ra lệnh:

```text
Mở trang biểu mẫu này, điền các trường theo bảng dữ liệu mình dán bên dưới, dừng lại trước khi bấm Gửi để mình kiểm tra.
```

AI điền các ô theo từng hàng dữ liệu. Phần "dừng lại trước khi gửi" rất quan trọng: bạn giữ quyền quyết định cuối cùng. Nếu trang yêu cầu đăng nhập, bạn tự đăng nhập trên cửa sổ trình duyệt hiện ra rồi mới giao tiếp việc.

### Lập trình viên kiểm tra giao diện web vừa viết

Bạn đang chạy trang web ở máy mình và muốn AI thử luồng đăng ký người dùng. Bạn viết:

```text
Mở trang web đang chạy trên máy mình, thử đăng ký tài khoản với email giả, báo cho mình những lỗi hiển thị hoặc nút nào không hoạt động.
```

README nói server còn có tùy chọn `--codegen` để chọn ngôn ngữ sinh mã (typescript, python, java, csharp hoặc none, mặc định là typescript). Nghĩa là bạn có thể đưa kết quả thử nghiệm sang bước viết test tự động. README cũng nhắc việc "self-healing tests" (test tự sửa) là một trường hợp hợp với MCP.

### Xem trang giao diện điện thoại

Bạn muốn biết trang của mình hiển thị thế nào trên điện thoại. Thêm tham số `--device` kèm tên máy, ví dụ "iPhone 15" (đúng ví dụ README đưa ra) vào `args`, rồi nhờ AI mở trang và mô tả những gì thấy. Cách này nhanh hơn việc tự đổi kích thước cửa sổ trình duyệt.

## Lỗi hay gặp và cách xử lý

### Dán cấu hình xong nhưng AI không thấy công cụ

Nguyên nhân hay gặp nhất là chưa khởi động lại ứng dụng, hoặc dán sai file cấu hình. Hãy đóng hẳn ứng dụng, mở lại, kiểm tra danh sách MCP server. Nếu vẫn không có, mở lại file cấu hình và xem JSON có thiếu dấu phẩy, dấu ngoặc không.

### Báo không có npx hoặc không tìm thấy lệnh

Nghĩa là Node.js chưa được cài hoặc terminal chưa nhận. Cài Node.js 18 trở lên, đóng và mở lại terminal, rồi chạy `node --version` để chắc chắn. Với ứng dụng giao diện (như Claude Desktop), cũng nên khởi động lại sau khi cài Node.js.

### Hết thời gian chờ khi lần đầu chạy

Lần đầu `npx` phải tải gói nên có thể lâu. Trong ví dụ của Cline, README đặt `"timeout": 30` và dùng `"-y"` trong `args` để `npx` không hỏi xác nhận. Bạn có thể làm theo nếu công cụ của bạn hay báo hết thời gian chờ.

### AI không vào được trang cục bộ hoặc tệp trong máy

Mặc định server chỉ cho truy cập tệp trong thư mục làm việc và chặn `file://`. Nếu thật sự cần mở rộng, bạn phải bật `--allow-unrestricted-file-access`. Hãy bật khi bạn hiểu rõ mình đang cho phép gì, và chỉ dùng trong máy bạn tin tưởng.

### Trình duyệt hiện lên làm phiền hoặc chạy trên máy chủ không có màn hình

Thêm `--headless` vào `args` để chạy ẩn. Với việc lỗi phát sinh do môi trường đặc biệt, README có tùy chọn `--no-sandbox`, nhưng đây là tùy chọn tắt lớp bảo vệ nên chỉ dùng khi thật cần. Repo cũng có Dockerfile nếu bạn muốn chạy trong container, xem thêm trong repo.

### Cảnh báo về giới hạn origin

`--allowed-origins` và `--blocked-origins` không phải ranh giới bảo mật theo chính README, và không ảnh hưởng tới chuyển hướng. Đừng dựa vào chúng như một lớp chặn tuyệt đối khi cho AI duyệt web.

## Có nên dùng không

Điểm mạnh: do Microsoft phát hành, giấy phép Apache-2.0, vẫn được cập nhật, cài đơn giản (một đoạn cấu hình hoặc một dòng lệnh), chạy được với rất nhiều ứng dụng AI, không cần mô hình đọc ảnh. Bạn cũng có nhiều tham số để kiểm soát trình duyệt, thư mục lưu tệp và quyền truy cập.

Giới hạn: chính README thừa nhận cách này tốn token hơn. Cây truy cập và định nghĩa công cụ chiếm nhiều chỗ trong bộ nhớ làm việc của mô hình. Với các coding agent phải xử lý mã nguồn lớn, README gợi ý nên xem Playwright CLI kèm SKILLS (một repo khác của Microsoft) vì tiết kiệm token hơn. MCP hợp hơn với các vòng lặp cần giữ trạng thái trình duyệt liên tục, như khám phá tự động, test tự sửa hoặc quy trình tự chủ chạy lâu.

Lưu ý thêm: AI thao tác trên web có thể bấm nhầm hoặc hiểu sai. Việc nhạy cảm như thanh toán, xóa dữ liệu, gửi biểu mẫu quan trọng thì nên để bạn duyệt lần cuối. Nếu bạn chỉ cần thu thập dữ liệu số lượng lớn đều đặn, một đoạn script Playwright viết sẵn có thể ổn định và rẻ hơn việc nhờ AI làm từng lần.

Tóm lại: nếu bạn đã dùng một ứng dụng AI hỗ trợ MCP và muốn nó biết duyệt web, đây là lựa chọn đáng thử đầu tiên.

## Câu hỏi thường gặp

### Playwright MCP có miễn phí không?

Repo dùng giấy phép Apache-2.0 và bạn chạy được bằng npx. README không nhắc phí cho chính server này. Chi phí (nếu có) đến từ ứng dụng hoặc mô hình AI bạn dùng kèm.

### Cần cài những gì để dùng?

Theo README, bạn cần Node.js 18 trở lên và một ứng dụng khách MCP như VS Code, Cursor, Windsurf, Claude Desktop, Goose, Grok, Junie hay công cụ tương tự. README không yêu cầu GPU hay API key riêng cho server này.

### Có chạy được trên Windows không?

README không nêu hạn chế hệ điều hành, chỉ yêu cầu Node.js 18 trở lên. Các lệnh như npx chạy được trong terminal trên Windows. Bạn nên tự thử, vì tư liệu chưa nói rõ về từng hệ điều hành.

### Khác gì so với Playwright CLI?

README giải thích: CLI kèm SKILLS tiết kiệm token hơn nên hợp với coding agent xử lý nhiều mã nguồn. MCP hợp với các vòng lặp cần giữ trạng thái trình duyệt liên tục, như khám phá tự động, test tự sửa hoặc quy trình chạy lâu.

### AI có đọc được ảnh màn hình không, có cần mô hình thị giác không?

Mặc định không cần. Server làm việc bằng cây truy cập (accessibility tree) dạng văn bản, nên không cần mô hình xử lý ảnh. README có tùy chọn --caps vision để bật thêm khả năng này nếu bạn cần.

### Dữ liệu và việc đăng nhập có an toàn không?

Có vài tùy chọn hỗ trợ: --isolated giữ hồ sơ trình duyệt trong bộ nhớ, mặc định truy cập tệp bị giới hạn trong thư mục làm việc. Tuy nhiên README nói rõ các tùy chọn lọc origin không phải ranh giới bảo mật. Hãy cẩn trọng khi cho AI thao tác trên tài khoản quan trọng.

### Có thể dùng trình duyệt đã đăng nhập sẵn của mình không?

Có, README có tùy chọn --extension để kết nối vào trình duyệt đang chạy (chỉ Edge hoặc Chrome) và cần cài tiện ích Playwright Extension. Chi tiết thêm xem trong README của repo.
