극작가 MCP 서버

극작가 MCP

Playwright를 사용하여 브라우저 자동화 기능을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 사용하면 LLM이 구조화된 접근성 스냅샷을 통해 웹 페이지와 상호 작용할 수 있으므로 스크린샷이나 시각적으로 조정된 모델이 필요하지 않습니다.

주요 특징

빠르고 가볍습니다 . 픽셀 기반 입력이 아닌 Playwright의 접근성 트리를 사용합니다.
LLM 친화적 : 비전 모델이 필요 없고, 구조화된 데이터로만 작동합니다.
결정론적 도구 적용 : 스크린샷 기반 접근 방식에서 흔히 나타나는 모호성을 방지합니다.

사용 사례

웹 탐색 및 양식 작성
구조화된 콘텐츠에서 데이터 추출
LLM이 주도하는 자동화 테스트
에이전트를 위한 일반 용도 브라우저 상호 작용

예제 구성

지엑스피1

VS Code에 설치

VS Code CLI를 사용하여 Playwright MCP 서버를 설치할 수 있습니다.

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

설치 후 Playwright MCP 서버를 VS Code의 GitHub Copilot 에이전트와 함께 사용할 수 있습니다.

명령줄

Playwright MCP 서버는 다음 명령줄 옵션을 지원합니다.

--browser <browser> : 사용할 브라우저 또는 크롬 채널입니다. 가능한 값은 다음과 같습니다.
- chrome , firefox , webkit , msedge
- 크롬 채널: chrome-beta , chrome-canary , chrome-dev
- 에지 채널: msedge-beta , msedge-canary , msedge-dev
- 기본값: chrome
--caps <caps> : 활성화할 기능 목록을 쉼표로 구분하여 표시합니다. 가능한 값은 다음과 같습니다: tabs, pdf, history, wait, files, install. 기본값은 all입니다.
--cdp-endpoint <endpoint> : 연결할 CDP 엔드포인트
--executable-path <path> : 브라우저 실행 파일의 경로
--headless : 브라우저를 헤드리스 모드로 실행합니다(기본적으로 headed 모드)
--device : 모바일 장치 에뮬레이션
--user-data-dir <path> : 사용자 데이터 디렉토리 경로
--port <port> : SSE 전송을 수신할 포트
--host <host> : 서버를 바인딩할 호스트입니다. 기본값은 localhost입니다. 모든 인터페이스에 바인딩하려면 0.0.0.0을 사용하세요.
--vision : 스크린샷을 사용하는 서버를 실행합니다(기본적으로 Aria 스냅샷이 사용됩니다)
--output-dir : 출력 파일을 위한 디렉토리
--config <path> : 구성 파일의 경로

사용자 프로필

Playwright MCP는 다음 위치에 있는 새 프로필로 브라우저를 시작합니다.

- `%USERPROFILE%\AppData\Local\ms-playwright\mcp-{channel}-profile` on Windows
- `~/Library/Caches/ms-playwright/mcp-{channel}-profile` on macOS
- `~/.cache/ms-playwright/mcp-{channel}-profile` on Linux

로그인한 모든 정보는 해당 프로필에 저장되며, 오프라인 상태를 지우려면 세션 간에 해당 정보를 삭제할 수 있습니다.

구성 파일

Playwright MCP 서버는 JSON 구성 파일을 사용하여 구성할 수 있습니다. 전체 구성 형식은 다음과 같습니다.

{
  // Browser configuration
  browser?: {
    // Browser type to use (chromium, firefox, or webkit)
    browserName?: 'chromium' | 'firefox' | 'webkit';

    // Path to user data directory for browser profile persistence
    userDataDir?: string;

    // Browser launch options (see Playwright docs)
    // @see https://playwright.dev/docs/api/class-browsertype#browser-type-launch
    launchOptions?: {
      channel?: string;        // Browser channel (e.g. 'chrome')
      headless?: boolean;      // Run in headless mode
      executablePath?: string; // Path to browser executable
      // ... other Playwright launch options
    };

    // Browser context options
    // @see https://playwright.dev/docs/api/class-browser#browser-new-context
    contextOptions?: {
      viewport?: { width: number, height: number };
      // ... other Playwright context options
    };

    // CDP endpoint for connecting to existing browser
    cdpEndpoint?: string;

    // Remote Playwright server endpoint
    remoteEndpoint?: string;
  },

  // Server configuration
  server?: {
    port?: number;  // Port to listen on
    host?: string;  // Host to bind to (default: localhost)
  },

  // List of enabled capabilities
  capabilities?: Array<
    'core' |    // Core browser automation
    'tabs' |    // Tab management
    'pdf' |     // PDF generation
    'history' | // Browser history
    'wait' |    // Wait utilities
    'files' |   // File handling
    'install' | // Browser installation
    'testing'   // Testing
  >;

  // Enable vision mode (screenshots instead of accessibility snapshots)
  vision?: boolean;

  // Directory for output files
  outputDir?: string;

  // Tool-specific configurations
  tools?: {
    browser_take_screenshot?: {
      // Disable base64-encoded image responses
      omitBase64?: boolean;
    }
  }
}

--config 명령줄 옵션을 사용하여 구성 파일을 지정할 수 있습니다.

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

리눅스에서 실행

디스플레이가 없는 시스템이나 IDE의 작업자 프로세스에서 헤더 브라우저를 실행하는 경우 DISPLAY가 있는 환경에서 MCP 서버를 실행하고 --port 플래그를 전달하여 SSE 전송을 활성화합니다.

npx @playwright/mcp@latest --port 8931

그런 다음 MCP 클라이언트 구성에서 url SSE 엔드포인트로 설정합니다.

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

도커

참고: Docker 구현은 현재 헤드리스 크로미엄만 지원합니다.

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "mcp/playwright"]
    }
  }
}

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

docker build -t mcp/playwright .

프로그래밍 방식 사용

import http from 'http';

import { createServer } 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 mcpServer = await createServer({ headless: true });
  const transport = new SSEServerTransport('/messages', res);
  await mcpServer.connect(transport);

  // ...
});

도구 모드

도구는 두 가지 모드로 제공됩니다.

스냅샷 모드 (기본값): 더 나은 성능과 안정성을 위해 접근성 스냅샷을 사용합니다.
비전 모드 : 시각적 기반 상호작용을 위해 스크린샷을 사용합니다.

Vision Mode를 사용하려면 서버를 시작할 때 --vision 플래그를 추가하세요.

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

제공된 스크린샷을 기준으로, 비전 모드는 XY 좌표 공간을 사용하여 요소와 상호 작용할 수 있는 컴퓨터 사용 모델에서 가장 잘 작동합니다.

스냅샷 기반 상호작용

브라우저 스냅샷
- 설명: 현재 페이지의 접근성 스냅샷을 캡처합니다. 스크린샷보다 낫습니다.
- 매개변수: 없음
브라우저 클릭
- 설명: 웹 페이지를 클릭합니다.
- 매개변수:
  - element (문자열): 요소와 상호 작용할 수 있는 권한을 얻는 데 사용되는 사람이 읽을 수 있는 요소 설명
  - ref (문자열): 페이지 스냅샷의 정확한 대상 요소 참조
브라우저 드래그
- 설명: 두 요소 사이에서 드래그 앤 드롭을 수행합니다.
- 매개변수:
  - startElement (문자열): 요소와 상호 작용할 수 있는 권한을 얻는 데 사용되는 사람이 읽을 수 있는 소스 요소 설명
  - startRef (문자열): 페이지 스냅샷의 정확한 소스 요소 참조
  - endElement (문자열): 요소와 상호 작용할 수 있는 권한을 얻는 데 사용되는 사람이 읽을 수 있는 대상 요소 설명
  - endRef (문자열): 페이지 스냅샷의 정확한 대상 요소 참조
브라우저_호버
- 설명: 페이지의 요소 위에 마우스를 올려 놓으세요
- 매개변수:
  - element (문자열): 요소와 상호 작용할 수 있는 권한을 얻는 데 사용되는 사람이 읽을 수 있는 요소 설명
  - ref (문자열): 페이지 스냅샷의 정확한 대상 요소 참조
브라우저_유형
- 설명: 편집 가능한 요소에 텍스트를 입력합니다.
- 매개변수:
  - element (문자열): 요소와 상호 작용할 수 있는 권한을 얻는 데 사용되는 사람이 읽을 수 있는 요소 설명
  - ref (문자열): 페이지 스냅샷의 정확한 대상 요소 참조
  - text (문자열): 요소에 입력할 텍스트
  - submit (부울, 선택 사항): 입력한 텍스트를 제출할지 여부(제출 후 Enter 키 누름)
  - slowly (부울, 선택 사항): 한 번에 한 글자씩 입력할지 여부입니다. 페이지에서 키 핸들러를 트리거하는 데 유용합니다. 기본적으로 전체 텍스트가 한 번에 채워집니다.
브라우저 선택 옵션
- 설명: 드롭다운에서 옵션을 선택하세요
- 매개변수:
  - element (문자열): 요소와 상호 작용할 수 있는 권한을 얻는 데 사용되는 사람이 읽을 수 있는 요소 설명
  - ref (문자열): 페이지 스냅샷의 정확한 대상 요소 참조
  - values (배열): 드롭다운에서 선택할 값의 배열입니다. 단일 값 또는 여러 값일 수 있습니다.
브라우저_스크린샷_찍기
- 설명: 현재 페이지의 스크린샷을 찍습니다. 스크린샷을 기반으로 다른 작업을 수행할 수 없으므로, 작업에는 browser_snapshot을 사용하세요.
- 매개변수:
  - raw (부울, 선택 사항): 압축하지 않고 PNG 형식으로 반환할지 여부입니다. 기본값은 false이며, JPEG 이미지를 반환합니다.
  - element (문자열, 선택 사항): 사람이 읽을 수 있는 요소 설명으로, 요소의 스크린샷 권한을 얻는 데 사용됩니다. 제공하지 않으면 뷰포트의 스크린샷이 촬영됩니다. element가 제공된 경우 ref도 함께 제공해야 합니다.
  - ref (문자열, 선택 사항): 페이지 스냅샷의 정확한 대상 요소 참조입니다. 지정하지 않으면 뷰포트의 스크린샷이 생성됩니다. ref가 지정되면 요소도 지정해야 합니다.

비전 기반 상호작용

브라우저 화면 캡처
- 설명: 현재 페이지의 스크린샷을 찍습니다.
- 매개변수: 없음
브라우저 화면 마우스 이동
- 설명: 마우스를 주어진 위치로 이동합니다.
- 매개변수:
  - element (문자열): 요소와 상호 작용할 수 있는 권한을 얻는 데 사용되는 사람이 읽을 수 있는 요소 설명
  - x (숫자): X 좌표
  - y (숫자): Y 좌표
브라우저 화면 클릭
- 설명: 마우스 왼쪽 버튼을 클릭하세요
- 매개변수:
  - element (문자열): 요소와 상호 작용할 수 있는 권한을 얻는 데 사용되는 사람이 읽을 수 있는 요소 설명
  - x (숫자): X 좌표
  - y (숫자): Y 좌표
브라우저 화면 드래그
- 설명: 마우스 왼쪽 버튼 드래그
- 매개변수:
  - element (문자열): 요소와 상호 작용할 수 있는 권한을 얻는 데 사용되는 사람이 읽을 수 있는 요소 설명
  - startX (숫자): 시작 X 좌표
  - startY (숫자): 시작 Y 좌표
  - endX (숫자): 끝 X 좌표
  - endY (숫자): 끝 Y 좌표
브라우저_화면_유형
- 설명: 텍스트를 입력하세요
- 매개변수:
  - text (문자열): 요소에 입력할 텍스트
  - submit (부울, 선택 사항): 입력한 텍스트를 제출할지 여부(제출 후 Enter 키 누름)

탭 관리

브라우저 탭 목록
- 설명: 브라우저 탭 나열
- 매개변수: 없음
브라우저_탭_새로 만들기
- 설명: 새 탭을 엽니다
- 매개변수:
  - url (문자열, 선택 사항): 새 탭에서 이동할 URL입니다. 지정하지 않으면 새 탭이 비어 있게 됩니다.
브라우저_탭_선택
- 설명: 인덱스로 탭 선택
- 매개변수:
  - index (숫자): 선택할 탭의 인덱스
브라우저 탭 닫기
- 설명: 탭 닫기
- 매개변수:
  - index (숫자, 선택 사항): 닫을 탭의 인덱스입니다. 지정하지 않으면 현재 탭을 닫습니다.

항해

브라우저 탐색
- 설명: URL로 이동합니다
- 매개변수:
  - url (문자열): 이동할 URL
브라우저_뒤로_탐색
- 설명: 이전 페이지로 돌아가기
- 매개변수: 없음
브라우저_탐색_포워드
- 설명: 다음 페이지로 이동합니다.
- 매개변수: 없음

건반

브라우저_누르기_키
- 설명: 키보드의 키를 누르세요
- 매개변수:
  - key (문자열): 누르려는 키의 이름 또는 생성할 문자(예: ArrowLeft``a

콘솔

브라우저 콘솔 메시지
- 설명: 모든 콘솔 메시지를 반환합니다.
- 매개변수: 없음

파일 및 미디어

브라우저 파일 업로드
- 설명: 하나 또는 여러 개의 파일을 업로드합니다.
- 매개변수:
  - paths (배열): 업로드할 파일의 절대 경로입니다. 단일 파일 또는 여러 파일일 수 있습니다.
브라우저_PDF_저장
- 설명: 페이지를 PDF로 저장
- 매개변수: 없음

유용

브라우저 닫기
- 설명: 페이지를 닫습니다
- 매개변수: 없음
브라우저 대기
- 설명: 지정된 시간(초) 동안 기다립니다.
- 매개변수:
  - time (숫자): 대기 시간(초)
브라우저 크기 조정
- 설명: 브라우저 창 크기 조정
- 매개변수:
  - width (숫자): 브라우저 창의 너비
  - height (숫자): 브라우저 창의 높이
브라우저 설치
- 설명: 설정에 지정된 브라우저를 설치합니다. 브라우저가 설치되지 않았다는 오류가 발생하면 이 메서드를 호출합니다.
- 매개변수: 없음
브라우저_핸들_대화 상자
- 설명: 대화 처리
- 매개변수:
  - accept (boolean): 대화를 수락할지 여부.
  - promptText (문자열, 선택 사항): 프롬프트 대화 상자의 경우 프롬프트의 텍스트입니다.

테스트

브라우저_생성_플레이라이트_테스트
- 설명: 주어진 시나리오에 대한 극작가 테스트 생성
- 매개변수:
  - name (문자열): 테스트의 이름
  - description (문자열): 테스트에 대한 설명
  - steps (배열): 테스트의 단계

Playwright MCP Server

Integrations