MCP server — điều khiển Clearcote bằng AI agent

Trỏ Claude Desktop, Cursor hoặc Cline tới MCP server của Clearcote và để model điều khiển một trình duyệt dùng chung qua 20 tool. Persona được thiết lập một lần qua biến môi trường, nên bộ tool vẫn gọn gàng — agent lo phần việc, còn danh tính bên dưới vẫn nhất quán.

Cấu hình MCP client

Thêm Clearcote vào cấu hình MCP của client (ví dụ dưới đây là Claude Desktop; Cursor/Cline dùng cùng cấu trúc):

{
  "mcpServers": {
    "clearcote": {
      "command": "npx",
      "args": ["-y", "clearcote-mcp"],
      "env": {
        "CLEARCOTE_FINGERPRINT": "acct-1",
        "CLEARCOTE_PLATFORM": "windows",
        "CLEARCOTE_PROXY": "http://host:8080",
        "CLEARCOTE_GEOIP": "1"
      }
    }
  }
}

Cả hai cách đều chạy cùng một Python server, nên bạn cần Python 3.10+. Hãy cài bằng pip trước — launcher npx sau đó sẽ dùng lại bản cài này — hoặc dùng "command": "clearcote-mcp" trong cấu hình. Việc ghim phiên bản mcp giữ server ở đúng phiên bản thư viện MCP mà nó được build cho (clearcote-mcp 0.1.0 không chạy được trên mcp 2.x):

pip install -U clearcote clearcote-mcp "mcp[cli]<2"

Không có khóa giấy phép, server sẽ chạy bản build mở. Thêm CLEARCOTE_LICENSE_KEY vào env (hoặc chạy clearcote login một lần) để chạy bản build có giấy phép mới nhất — Miễn phí với GitHub hoặc Pro. Khóa miễn phí cần SDK clearcote 0.30.0 trở lên, và lệnh ở trên sẽ cài phiên bản đáp ứng yêu cầu đó.

Các tool

Một trình duyệt dùng chung được điều khiển bởi hai mươi tool:

…cùng với get_page_html, evaluate_js, current_page, get_cookies (chỉ đọc) và save_page_pdf (chỉ ở chế độ headless). Agent đọc trang, ra quyết định rồi hành động — tất cả thông qua một instance Clearcote duy nhất với persona nhất quán.

Persona qua biến môi trường

Các thiết lập persona cơ bản được đặt bằng biến môi trường CLEARCOTE_*, nên model không bao giờ phải bận tâm đến danh tính. Với các tùy chọn fingerprint còn lại, hãy dùng SDK trực tiếp.

CLEARCOTE_FINGERPRINT=acct-1          # seed -> stable identity
CLEARCOTE_PLATFORM=windows            # windows | linux | macos | android
CLEARCOTE_BRAND=Edge                  # Chrome (default) | Edge | Opera | Vivaldi
CLEARCOTE_ACCEPT_LANGUAGE=en-US
CLEARCOTE_TIMEZONE=America/New_York
CLEARCOTE_PROXY=http://user:pass@host:8080
CLEARCOTE_GEOIP=1                     # timezone + language + WebRTC follow the proxy exit
CLEARCOTE_HEADLESS=0                  # show the window (default: headless)
CLEARCOTE_LICENSE_KEY=cc_lic_...      # optional -> the latest licensed build

Proxy có xác thực cần bản build có giấy phép; bản build mở không thể truyền thông tin đăng nhập proxy cho trình duyệt.

Cơ chế bảo vệ

• Các lệnh gọi tool có URL trỏ tới localhost, mạng nội bộ hoặc endpoint metadata của cloud sẽ bị từ chối. Đây là lớp chặn để phòng sai sót, không phải sandbox: script chạy bằng evaluate_js và các link mà trang tự đi theo vẫn có thể truy cập những địa chỉ đó. Đặt CLEARCOTE_ALLOW_PRIVATE_EGRESS=1 để cho phép (ví dụ, khi cần test một dev server chạy local).
• Ảnh chụp màn hình, file PDF và session đã lưu được ghi vào <temp>/clearcote-mcp (dùng CLEARCOTE_MCP_WRITE_DIR để chuyển sang thư mục khác).
• Mỗi lệnh gọi tool sẽ timeout sau 90 giây (CLEARCOTE_MCP_TOOL_TIMEOUT).
• Trình duyệt khởi động ngay khi MCP client khởi chạy server. Với khóa Miễn phí với GitHub, việc này chiếm ngay suất trình duyệt duy nhất của bạn; đặt CLEARCOTE_MCP_PREWARM=0 để trình duyệt chỉ khởi động ở lần gọi tool đầu tiên.

MCP server khởi chạy trình duyệt trực tiếp, không kèm cờ automation của Playwright, nên navigator.webdriver vẫn là false và engine giữ các tác dụng phụ thường gặp của CDP tách biệt khỏi trang. Có hai cách tự động hóa: một LLM bên ngoài trình duyệt (chính MCP server này) hoặc AI agent trong trình duyệt chạy ngay bên trong tiến trình.

Cần một endpoint thuần thay vì MCP? Xem Triển khai & Docker.