본문으로 건너뛰기
MCP 서버 전체 목록

Playwright MCP

Playwright로 에이전트가 브라우저를 열고 페이지를 읽고 클릭 · 입력하게 해 주는 MCP 서버. 접근성 스냅샷 기반. Apache-2.0

원본:microsoft/playwright-mcp

설치 방법은 설치 탭에 정리했어요.

설명

Playwright MCP

Playwright로 브라우저 자동화를 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. LLM이 스크린샷이나 시각에 맞춰 다듬은 모델 없이도, 구조화된 접근성 스냅샷으로 웹 페이지와 상호작용할 수 있게 해 줍니다.

Playwright MCP와 Playwright CLI

이 패키지는 Playwright의 MCP 인터페이스를 제공합니다. 코딩 에이전트를 쓴다면 CLI+SKILLS가 더 나을 수 있습니다.

  • CLI: 요즘 코딩 에이전트는 MCP보다 SKILL로 노출한 CLI 기반 워크플로를 점점 더 선호합니다. CLI 호출이 토큰을 더 적게 쓰기 때문입니다. 큰 도구 스키마와 장황한 접근성 트리를 모델 컨텍스트에 싣지 않고, 간결하고 목적에 맞춘 명령으로 행동할 수 있습니다. 그래서 큰 코드베이스, 테스트, 추론을 한정된 컨텍스트 창 안에서 함께 다뤄야 하는 처리량 높은 코딩 에이전트에는 CLI + SKILL이 더 알맞습니다. SKILL을 쓰는 Playwright CLI에 대해 더 알아보세요.
  • MCP: 지속되는 상태, 풍부한 내부 관찰, 페이지 구조에 대한 반복 추론이 도움이 되는 특수한 에이전트 루프에서는 MCP가 여전히 쓸모 있습니다. 탐색적 자동화, 스스로 고치는 테스트, 토큰 비용보다 끊김 없는 브라우저 컨텍스트 유지가 더 중요한 오래 도는 자율 워크플로 같은 경우입니다.

주요 특징

  • 빠르고 가볍습니다. 픽셀 기반 입력이 아니라 Playwright의 접근성 트리를 씁니다.
  • LLM 친화적입니다. 비전 모델이 필요 없고 구조화된 데이터만으로 동작합니다.
  • 결정적인 도구 적용. 스크린샷 기반 방식에서 흔한 모호함을 피합니다.

요구 사항

  • Node.js 18 이상
  • VS Code, Cursor, Windsurf, Claude Desktop, Goose, Grok, Junie 같은 MCP 클라이언트

시작하기

먼저 쓰는 클라이언트에 Playwright MCP 서버를 설치하세요.

표준 설정은 대부분의 도구에서 통합니다.

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

VS Code에 설치 VS Code Insiders에 설치

Amp

Amp VS Code 확장의 설정 화면에서 추가하거나 settings.json 파일을 고쳐서 추가하세요.

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

Amp CLI 설정: 아래 amp mcp add 명령으로 추가하세요.

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

Antigravity

Antigravity 설정이나 구성 파일을 고쳐서 추가하세요.

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

Claude Code

Claude Code CLI로 Playwright MCP 서버를 추가하세요.

claude mcp add playwright npx @playwright/mcp@latest

Claude Desktop

MCP 설치 가이드를 따르고, 위의 표준 설정을 쓰세요.

Cline

MCP 서버 설정하기 절의 안내를 따르세요.

예시: 로컬 설정

cline_mcp_settings.json 파일에 다음을 추가하세요.

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "timeout": 30,
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ],
      "disabled": false
    }
  }
}

Codex

Codex CLI로 Playwright MCP 서버를 추가하세요.

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

또는 설정 파일 ~/.codex/config.toml을 만들거나 고쳐서 다음을 추가하세요.

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

자세한 내용은 Codex MCP 문서를 보세요.

Copilot

Copilot CLI로 Playwright MCP 서버를 대화형으로 추가하세요.

/mcp add

또는 설정 파일 ~/.copilot/mcp-config.json을 만들거나 고쳐서 다음을 추가하세요.

{
  "mcpServers": {
    "playwright": {
      "type": "local",
      "command": "npx",
      "tools": [
        "*"
      ],
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

자세한 내용은 Copilot CLI 문서를 보세요.

Cursor

단추를 눌러 설치하기

Cursor에 설치

또는 직접 설치하기

Cursor Settings → MCP → Add new MCP Server로 가세요. 이름은 원하는 대로 정하고, command 종류에 npx @playwright/mcp@latest 명령을 쓰세요. Edit를 눌러 설정을 확인하거나 명령에 인자를 더할 수도 있습니다.

Factory

Factory CLI로 Playwright MCP 서버를 추가하세요.

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

또는 Factory droid 안에서 /mcp를 입력해 MCP 서버를 관리하는 대화형 UI를 여세요.

자세한 내용은 Factory MCP 문서를 보세요.

Gemini CLI

MCP 설치 가이드를 따르고, 위의 표준 설정을 쓰세요.

Goose

단추를 눌러 설치하기

Goose에 설치

또는 직접 설치하기

Advanced settings → Extensions → Add custom extension으로 가세요. 이름은 원하는 대로 정하고, 종류는 STDIO, command는 npx @playwright/mcp로 두세요. "Add Extension"을 누르세요.

Grok

Grok CLI로 Playwright MCP 서버를 추가하세요.

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

또는 설정 파일 ~/.grok/config.toml을 만들거나 고쳐서 다음을 추가하세요.

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

자세한 내용은 Grok MCP 문서를 보세요.

Junie

Junie CLI에 Playwright MCP 서버를 추가하려면 다음과 같이 하세요.

  1. /mcp를 입력합니다
  2. Ctrl+A를 눌러 새 MCP 서버를 추가합니다
  3. 목록에서 Playwright를 고릅니다

또는 .junie/mcp/mcp.json에 추가하세요.

{
  "mcpServers": {
    "Playwright": {
      "command": "npx",
      "args": [
        "-y",
        "@playwright/mcp@latest"
      ]
    }
  }
}

자세한 내용은 Junie MCP 설정 문서를 보세요.

Kiro

Kiro에 추가

MCP 서버 문서를 따르세요. 예를 들어 .kiro/settings/mcp.json에 다음과 같이 넣습니다.

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

LM Studio

단추를 눌러 설치하기

LM Studio에 Playwright MCP 서버 추가

또는 직접 설치하기

오른쪽 사이드바의 Program → Install → Edit mcp.json으로 가서 위의 표준 설정을 쓰세요.

opencode

MCP 서버 문서를 따르세요. 예를 들어 ~/.config/opencode/opencode.json에 다음과 같이 넣습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "@playwright/mcp@latest"
      ],
      "enabled": true
    }
  }
}

Qodo Gen

VSCode나 IntelliJ에서 Qodo Gen 채팅 패널을 열고 → Connect more tools → + Add new MCP → 위의 표준 설정을 붙여 넣으세요. 저장(Save)을 누르면 됩니다.

VS Code

단추를 눌러 설치하기

위의 VS Code 단추와 VS Code Insiders 단추를 누르세요.

또는 직접 설치하기

MCP 설치 가이드를 따르고 위의 표준 설정을 쓰세요. VS Code CLI로도 Playwright MCP 서버를 설치할 수 있습니다.

# For VS Code
code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'

설치한 뒤에는 VS Code의 GitHub Copilot 에이전트에서 Playwright MCP 서버를 쓸 수 있습니다.

Warp

Settings → AI → Manage MCP Servers → + Add로 가서 MCP 서버를 추가하세요. 위의 표준 설정을 쓰세요.

또는 Warp 프롬프트에서 슬래시 명령 /add-mcp를 쓰고 위의 표준 설정을 붙여 넣으세요.

Windsurf

Windsurf MCP 문서를 따르고 위의 표준 설정을 쓰세요.

설정

Playwright MCP 서버는 다음 인자를 지원합니다. 위 JSON 설정의 "args" 목록에 넣을 수 있습니다. 아래는 그중 자주 쓰는 옵션이고, 전체 옵션 표는 원문 README의 「Configuration」 절에 있습니다.

옵션설명
--browser쓸 브라우저 또는 Chrome 채널: chrome, firefox, webkit, msedge. 환경 변수 PLAYWRIGHT_MCP_BROWSER
--headless브라우저를 헤드리스 모드로 실행합니다. 기본은 화면이 있는 모드입니다. 환경 변수 PLAYWRIGHT_MCP_HEADLESS
--isolated브라우저 프로필을 디스크가 아니라 메모리에 둡니다. 환경 변수 PLAYWRIGHT_MCP_ISOLATED
--user-data-dir사용자 데이터 디렉터리 경로. 정하지 않으면 임시 디렉터리를 만듭니다. 환경 변수 PLAYWRIGHT_MCP_USER_DATA_DIR
--storage-state격리 세션에서 쓸 스토리지 상태 파일 경로. 환경 변수 PLAYWRIGHT_MCP_STORAGE_STATE
--extension실행 중인 브라우저 인스턴스에 연결합니다(Edge/Chrome만). 「Playwright Extension」 설치가 필요합니다. 환경 변수 PLAYWRIGHT_MCP_EXTENSION
--caps켤 추가 기능을 쉼표로 나열합니다. 가능한 값: vision, pdf, devtools. 환경 변수 PLAYWRIGHT_MCP_CAPS
--cdp-endpoint연결할 CDP 엔드포인트. 환경 변수 PLAYWRIGHT_MCP_CDP_ENDPOINT
--config설정 파일 경로. 환경 변수 PLAYWRIGHT_MCP_CONFIG
--device에뮬레이션할 기기. 예: "iPhone 15". 환경 변수 PLAYWRIGHT_MCP_DEVICE
--mobile일반 모바일 기기(Chromium은 Pixel 10, WebKit은 iPhone 17)를 에뮬레이션합니다. 모바일 페이지는 대체로 가벼워 토큰을 아낍니다. --device와 함께 쓸 수 없습니다. 환경 변수 PLAYWRIGHT_MCP_MOBILE
--viewport-size브라우저 뷰포트 크기(픽셀). 예: "1280x720". 환경 변수 PLAYWRIGHT_MCP_VIEWPORT_SIZE
--allowed-origins브라우저가 요청해도 되는 신뢰하는 출처를 세미콜론으로 나열합니다. 기본은 모두 허용입니다. 중요: 보안 경계가 아니며 리디렉션에는 영향을 주지 않습니다. 환경 변수 PLAYWRIGHT_MCP_ALLOWED_ORIGINS
--blocked-origins브라우저의 요청을 막을 출처를 세미콜론으로 나열합니다. 차단 목록을 먼저 평가합니다. 환경 변수 PLAYWRIGHT_MCP_BLOCKED_ORIGINS
--allow-unrestricted-file-access작업 공간 루트 밖의 파일 접근을 허용하고 file:// 주소에도 제한 없이 접근할 수 있게 합니다. 기본은 작업 공간 루트(루트가 없으면 현재 디렉터리)로 제한하고 file:// 이동을 막습니다. 환경 변수 PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS
--portSSE 전송에서 수신할 포트. 환경 변수 PLAYWRIGHT_MCP_PORT
--proxy-server프록시 서버 지정. 예: "http://myproxy:3128", "socks5://myproxy:8080". 환경 변수 PLAYWRIGHT_MCP_PROXY_SERVER
--secretsdotenv 형식의 비밀 값이 든 파일 경로. 환경 변수 PLAYWRIGHT_MCP_SECRETS_FILE
--snapshot-mode응답용 스냅샷을 찍을 때 쓸 모드: "full" 또는 "none". 기본은 "full". 환경 변수 PLAYWRIGHT_MCP_SNAPSHOT_MODE
--timeout-action동작 제한 시간(밀리초). 기본 5000ms. 환경 변수 PLAYWRIGHT_MCP_TIMEOUT_ACTION
--timeout-navigation이동 제한 시간(밀리초). 기본 60000ms. 환경 변수 PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION

사용자 프로필

Playwright MCP는 일반 브라우저처럼 지속되는 프로필로 실행하거나(기본), 테스트 세션용 격리 컨텍스트로 실행하거나, 브라우저 확장으로 이미 쓰고 있는 브라우저에 연결할 수 있습니다.

지속되는 프로필

로그인 정보는 모두 지속 프로필에 저장되며, 오프라인 상태를 비우고 싶으면 세션 사이에 지워도 됩니다. 지속 프로필은 다음 위치에 있고, --user-data-dir 인자로 바꿀 수 있습니다.

# Windows
%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-{workspace-hash}

# macOS
- ~/Library/Caches/ms-playwright/mcp-{channel}-{workspace-hash}

# Linux
- ~/.cache/ms-playwright/mcp-{channel}-{workspace-hash}

{workspace-hash}는 MCP 클라이언트의 작업 공간 루트에서 나오므로, 프로젝트마다 프로필이 자동으로 나뉩니다.

💡 중요 지속 프로필은 한 번에 브라우저 인스턴스 하나만 쓸 수 있어서, 같은 작업 공간을 공유하는 MCP 클라이언트 여럿이 동시에 쓰면 충돌합니다. 여러 클라이언트를 함께 돌리려면 추가 클라이언트마다 --isolated로 시작하거나 서로 다른 --user-data-dir을 가리키세요.

격리

격리 모드에서는 세션마다 격리된 프로필로 시작합니다. MCP에 브라우저를 닫아 달라고 할 때마다 세션이 닫히고 그 세션의 스토리지 상태는 모두 사라집니다. 설정의 contextOptions나 --storage-state 인자로 브라우저에 초기 스토리지 상태를 줄 수 있습니다. 스토리지 상태에 대해서는 여기에서 더 알아보세요.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--isolated",
        "--storage-state={path/to/storage.json}"
      ]
    }
  }
}

브라우저 확장

Playwright MCP Chrome 확장을 쓰면 이미 열려 있는 브라우저 탭에 연결해 로그인된 세션과 브라우저 상태를 그대로 쓸 수 있습니다. 설치와 설정 방법은 microsoft/playwright › packages/extension을 보세요.

초기 상태

브라우저 컨텍스트나 페이지에 초기 상태를 주는 방법이 여러 가지 있습니다.

스토리지 상태는 다음 둘 중 하나로 줄 수 있습니다.

  • --user-data-dir 인자로 사용자 데이터 디렉터리에서 시작합니다. 세션 사이에 브라우저 데이터가 모두 유지됩니다.
  • --storage-state 인자로 스토리지 상태 파일에서 시작합니다. 파일의 쿠키와 로컬 스토리지를 격리된 브라우저 컨텍스트에 불러옵니다.

페이지 상태는 다음을 쓸 수 있습니다.

  • --init-page로 Playwright 페이지 객체에서 실행할 TypeScript 파일을 지정합니다. 페이지를 준비하는 임의의 코드를 돌릴 수 있습니다.
// init-page.ts
export default async ({ page }) => {
  await page.context().grantPermissions(['geolocation']);
  await page.context().setGeolocation({ latitude: 37.7749, longitude: -122.4194 });
  await page.setViewportSize({ width: 1280, height: 720 });
};
  • --init-script로 초기화 스크립트로 추가할 JavaScript 파일을 지정합니다. 스크립트는 모든 페이지에서 그 페이지의 스크립트보다 먼저 실행됩니다. 브라우저 API를 덮어쓰거나 환경을 준비할 때 유용합니다.
// init-script.js
window.isPlaywrightMCP = true;

설정 파일

Playwright MCP 서버는 JSON 설정 파일로도 설정할 수 있습니다. --config 명령줄 옵션으로 설정 파일을 지정하세요.

npx @playwright/mcp@latest --config path/to/config.json

설정 파일에는 browser(브라우저 종류 · 격리 · 사용자 데이터 디렉터리 · 실행 옵션 · CDP), extension, server(포트 · 호스트), capabilities, saveSession, secrets, outputDir, console, network(허용 · 차단 출처), testIdAttribute, timeouts, imageResponses, filePaths, snapshot, codegen 같은 항목이 있습니다. 전체 스키마는 원문 README의 「Configuration file」 절에 있습니다.

독립 실행 MCP 서버

화면이 없는 시스템에서 헤드 있는 브라우저를 돌리거나 IDE의 작업 프로세스에서 실행할 때는, DISPLAY가 있는 환경에서 MCP 서버를 실행하고 --port 플래그를 넘겨 HTTP 전송을 켜세요.

npx @playwright/mcp@latest --port 8931

그런 다음 MCP 클라이언트 설정의 url을 그 HTTP 엔드포인트로 지정하세요.

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

보안

Playwright MCP는 보안 경계가 아닙니다. 배포를 안전하게 하는 방법은 MCP 보안 모범 사례를 보세요.

Docker

참고: Docker 구현은 지금 헤드리스 Chromium만 지원합니다.

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

MCP 클라이언트가 컨테이너를 띄우게 하지 않고 오래 도는 서비스로 실행하려면 이렇게 하세요.

docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  --name playwright \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  /app/cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0

서버는 호스트 포트 8931에서 수신하며 어떤 MCP 클라이언트든 붙을 수 있습니다.

Docker 이미지를 직접 빌드할 수도 있습니다.

docker build -t mcr.microsoft.com/playwright/mcp .

프로그램에서 쓰기

import http from 'http';

import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // ...

  // Creates a headless Playwright MCP server with SSE transport
  const connection = await createConnection({ browser: { launchOptions: { headless: true } } });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);

  // ...
});

도구

핵심 자동화

  • browser_click: 웹 페이지에서 클릭합니다
  • browser_close: 페이지를 닫습니다
  • browser_console_messages: 콘솔 메시지를 모두 돌려줍니다
  • browser_drag: 두 요소 사이에서 끌어서 놓기를 합니다
  • browser_drop: 파일이나 데이터를 요소 위에 놓습니다
  • browser_emulate_media: 페이지의 CSS 미디어 기능을 에뮬레이션합니다
  • browser_evaluate: 페이지나 요소에서 JavaScript 식을 평가합니다
  • browser_file_upload: 파일을 하나 또는 여러 개 올립니다
  • browser_fill_form: 여러 폼 필드를 채웁니다
  • browser_find: 접근성 스냅샷에서 검색합니다
  • browser_handle_dialog: 대화 상자를 처리합니다
  • browser_hover: 페이지의 요소 위에 마우스를 올립니다
  • browser_navigate: 주소로 이동합니다
  • browser_navigate_back: 이전 페이지로 돌아갑니다
  • browser_network_request: 네트워크 요청의 상세를 보여 줍니다
  • browser_network_requests: 네트워크 요청 목록을 보여 줍니다
  • browser_press_key: 키보드 키를 누릅니다
  • browser_resize: 브라우저 창 크기를 바꿉니다
  • browser_run_code_unsafe: Playwright 코드를 실행합니다(안전하지 않음)
  • browser_select_option: 드롭다운에서 옵션을 고릅니다
  • browser_snapshot: 접근성 스냅샷을 찍습니다
  • browser_take_screenshot: 스크린샷을 찍습니다
  • browser_type: 편집 가능한 요소에 글자를 입력합니다
  • browser_wait_for: 글자나 시간을 기다립니다

탭 관리

  • browser_tabs: 브라우저 탭을 나열하고, 만들고, 닫고, 고릅니다

설정

  • browser_get_config: 최종으로 정해진 설정을 가져옵니다

네트워크

  • browser_network_state_set: 브라우저의 네트워크 상태를 정합니다
  • browser_route: 네트워크 요청을 모의합니다
  • browser_route_list: 켜져 있는 네트워크 라우트를 모두 나열합니다
  • browser_unroute: 네트워크 라우트를 지웁니다

스토리지

  • 쿠키: browser_cookie_clear, browser_cookie_delete, browser_cookie_get, browser_cookie_list, browser_cookie_set
  • 로컬 스토리지: browser_localstorage_clear, browser_localstorage_delete, browser_localstorage_get, browser_localstorage_list, browser_localstorage_set
  • 세션 스토리지: browser_sessionstorage_clear, browser_sessionstorage_delete, browser_sessionstorage_get, browser_sessionstorage_list, browser_sessionstorage_set
  • browser_set_storage_state: 스토리지 상태를 복원합니다
  • browser_storage_state: 스토리지 상태를 저장합니다

개발자 도구 (--caps=devtools)

  • browser_annotate: 현재 페이지에 주석을 답니다
  • browser_hide_highlight: 요소 강조를 지웁니다
  • browser_highlight: 계속 남는 강조 오버레이를 보여 줍니다
  • browser_resume: 멈춘 스크립트 실행을 재개합니다
  • browser_start_recording: 사용자 동작 기록을 시작합니다
  • browser_start_tracing: 트레이스 기록을 시작합니다
  • browser_start_video: 영상 녹화를 시작합니다
  • browser_stop_recording: 기록을 멈추고 코드를 돌려줍니다
  • browser_stop_tracing: 트레이스 기록을 멈춥니다
  • browser_stop_video: 영상 녹화를 멈춥니다
  • browser_video_chapter: 영상에 챕터 표시를 더합니다
  • browser_video_hide_actions: 동작 주석 표시를 멈춥니다
  • browser_video_show_actions: 이후 동작에 주석을 표시합니다

좌표 기반 (--caps=vision)

  • browser_mouse_click_xy: 지정한 위치를 클릭합니다
  • browser_mouse_down: 마우스 단추를 누릅니다
  • browser_mouse_drag_xy: 지정한 위치까지 끕니다
  • browser_mouse_move_xy: 마우스를 지정한 위치로 옮깁니다
  • browser_mouse_up: 마우스 단추를 뗍니다
  • browser_mouse_wheel: 마우스 휠을 굴립니다

PDF 만들기 (--caps=pdf)

  • browser_pdf_save: 페이지를 PDF로 저장합니다

테스트 검증

  • browser_generate_locator: 요소의 로케이터를 만듭니다
  • browser_verify_element_visible: 요소가 보이는지 검증합니다
  • browser_verify_list_visible: 목록이 보이는지 검증합니다
  • browser_verify_text_visible: 글자가 보이는지 검증합니다
  • browser_verify_value: 요소의 값을 검증합니다

더 알아보기