Playwright MCP Server 🎭

Playwright를 사용하여 브라우저 자동화 기능을 제공하는 Model Context Protocol 서버입니다. 이 서버는 LLM이 실제 브라우저 환경에서 웹 페이지와 상호 작용하고, 스크린샷을 찍고, 테스트 코드를 생성하며, 페이지를 웹 스크래핑하고, JavaScript를 실행할 수 있게 합니다.

✨ v1.0.10의 새로운 기능

🎯 143개의 실제 기기 프리셋을 지원하는 기기 에뮬레이션!

간단한 명령으로 실제 기기 프로필에서 웹 애플리케이션을 테스트하세요:

// Test on iPhone 13 with automatic user-agent, touch support, and device pixel ratio
await playwright_resize({ device: "iPhone 13" });

// Switch to iPad with landscape orientation
await playwright_resize({ device: "iPad Pro 11", orientation: "landscape" });

// Test desktop view
await playwright_resize({ device: "Desktop Chrome" });

AI 어시스턴트를 위한 자연어 지원:

• "iPhone 13에서 테스트"

• "iPad 보기로 전환"

• "가로 모드로 회전"

143개 기기 지원: 뷰포트, 사용자 에이전트, 터치 이벤트, 기기 픽셀 비율을 적절하게 에뮬레이션하는 iPhone, iPad, Pixel, Galaxy 및 데스크톱 브라우저를 지원합니다.

📚 기기 빠른 참조 보기 | 프롬프트 가이드

Related MCP server: Cloudflare Playwright MCP

스크린샷

문서 | API 레퍼런스

설치

npm, mcp-get 또는 Smithery를 사용하여 패키지를 설치할 수 있습니다:

npm으로:

npm install -g @executeautomation/playwright-mcp-server

mcp-get으로 사용:

npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server

Smithery 사용

Smithery를 통해 Playwright MCP를 Claude Desktop에 자동으로 설치하려면:

npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude

Claude Code 사용:

claude mcp add --transport stdio playwright npx @executeautomation/playwright-mcp-server

VS Code에 설치

다음 버튼 중 하나를 사용하여 VS Code에 Playwright MCP 서버를 설치하세요:

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

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

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

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

브라우저 설치

자동 설치 (권장)

Playwright MCP Server는 처음 사용할 때 브라우저 바이너리를 자동으로 설치합니다. 서버가 브라우저가 누락되었음을 감지하면 다음을 수행합니다:

1. 필요한 브라우저(Chromium, Firefox, WebKit)를 자동으로 다운로드하여 설치합니다

2. 콘솔에 설치 진행 상황을 표시합니다

3. 설치가 완료되면 요청을 다시 시도합니다

수동 설정이 필요하지 않습니다! 서버를 사용하기만 하면 브라우저 설치를 자동으로 처리합니다.

수동 설치 (선택 사항)

브라우저를 직접 설치하거나 자동 설치에 문제가 있는 경우 다음을 사용하세요:

# Install all browsers
npx playwright install

# Or install specific browsers
npx playwright install chromium
npx playwright install firefox
npx playwright install webkit

브라우저 저장 위치

브라우저는 다음 위치에 설치됩니다:

• Windows: %USERPROFILE%\AppData\Local\ms-playwright

• macOS: ~/Library/Caches/ms-playwright

• Linux: ~/.cache/ms-playwright

Playwright 서버를 사용하기 위한 구성

표준 모드 (stdio)

이것은 Claude Desktop에 권장되는 모드입니다.

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

참고: stdio 모드에서는 깨끗한 JSON-RPC 통신을 유지하기 위해 로그가 자동으로 파일에만 기록됩니다(콘솔에는 기록되지 않음). 로그는 ~/playwright-mcp-server.log에 기록됩니다.

HTTP 모드 (독립 실행형 서버)

디스플레이가 없는 시스템에서 헤드드 브라우저를 실행하거나 IDE의 워커 프로세스에서 실행하는 경우 MCP 서버를 독립 실행형 HTTP 서버로 실행할 수 있습니다:

Claude Desktop 사용자 참고 사항: Claude Desktop은 현재 stdio 모드(명령/인수 구성)가 필요합니다. HTTP 모드는 VS Code, 사용자 지정 클라이언트 및 원격 배포에 권장됩니다. 자세한 내용은 CLAUDE_DESKTOP_CONFIG.md을 참조하세요.

HTTP 서버 시작

# Using npx
npx @executeautomation/playwright-mcp-server --port 8931

# Or after global installation
playwright-mcp-server --port 8931

서버가 시작되면 사용 가능한 엔드포인트를 표시합니다:

==============================================
Playwright MCP Server (HTTP Mode)
==============================================
Port: 8931

ENDPOINTS:
- SSE Stream:     GET  http://localhost:8931/sse
- Messages:       POST http://localhost:8931/messages?sessionId=<id>
- MCP (unified):  GET  http://localhost:8931/mcp
- MCP (unified):  POST http://localhost:8931/mcp?sessionId=<id>
- Health Check:   GET  http://localhost:8931/health
==============================================

HTTP 모드용 클라이언트 구성

⚠️ 중요: HTTP/SSE 전송에는 "type": "http" 필드가 필수입니다!

VS Code GitHub Copilot용:

{
  "github.copilot.chat.mcp.servers": {
    "playwright": {
      "url": "http://localhost:8931/mcp",
      "type": "http"
    }
  }
}

사용자 지정 MCP 클라이언트용:

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

중요: "type": "http"가 없으면 연결이 실패합니다.

Claude Desktop의 경우: 대신 stdio 모드를 사용하세요 (위 표준 모드 참조)

HTTP 모드의 사용 사례

• 디스플레이가 없는 시스템(예: 원격 서버)에서 헤드드 브라우저 실행

• VS Code GitHub Copilot와 통합

• 서버를 백그라운드 서비스로 실행

• 여러 클라이언트에서 서버에 액세스

• /health 엔드포인트로 디버깅

• 사용자 지정 MCP 클라이언트 통합

모니터링: 서버에는 동적으로 할당된 포트(충돌 방지)에서 시작되는 모니터링 시스템이 포함되어 있습니다. 실제 포트는 콘솔 출력에서 확인하세요.

참고: Claude Desktop의 경우 지금은 계속 표준 모드(위 표준 모드)를 사용하세요.

문제 해결

"No transport found for sessionId" 오류

증상: "Bad Request: No transport found for sessionId" 메시지와 함께 400 오류 발생

해결 방법:

1. 구성에 "type": "http"가 포함되어 있는지 확인합니다

   {
     "url": "http://localhost:8931/mcp",
     "type": "http"  // ← This is REQUIRED!
   }

2. 서버 로그에 연결이 표시되는지 확인합니다:

   # Should see these in order:
   # 1. "Incoming request" - GET /mcp
   # 2. "Transport registered" - with sessionId
   # 3. "POST message received" - with same sessionId

3. 서버와 클라이언트를 모두 다시 시작합니다

연결 문제

• 서버가 시작되지 않는 경우: 포트 8931이 사용 가능한지 확인하세요

• 외부 액세스 차단: 이는 보안상 의도된 설계입니다. 서버는 localhost에만 바인딩됩니다

• 원격 액세스의 경우: SSH 터널링을 사용하세요:

  ssh -L 8931:localhost:8931 user@remote-server

테스트

이 프로젝트는 Jest를 사용하여 테스트합니다. 테스트는 src/__tests__ 디렉터리에 있습니다.

테스트 실행

다음 명령 중 하나로 테스트를 실행할 수 있습니다:

# Run tests using the custom script (with coverage)
node run-tests.cjs

# Run tests using npm scripts
npm test           # Run tests without coverage
npm run test:coverage  # Run tests with coverage
npm run test:custom    # Run tests with custom script (same as node run-tests.cjs)

테스트 커버리지 리포트는 coverage 디렉터리에 생성됩니다.

evals 실행

evals 패키지는 mcp 클라이언트를 로드하여 index.ts 파일을 실행하므로 테스트 사이에 재빌드할 필요가 없습니다. npx 명령 앞에 접두사를 붙여 환경 변수를 로드할 수 있습니다. 전체 문서는 여기에서 확인할 수 있습니다.

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/tools/codegen/index.ts

기여

새 도구를 추가할 때는 도구 이름 길이에 유의하십시오. Cursor와 같은 일부 클라이언트는 서버 이름과 도구 이름의 조합(server_name:tool_name)에 대해 60자 제한이 있습니다.

우리 서버 이름은 playwright-mcp입니다. 도구 이름이 이 제한을 초과하지 않을 만큼 충분히 짧도록 하세요.

Star History