Claude Desktop에 Playwright MCP 서버 연결해서 웹 자동화하기

Playwright MCP 서버란 무엇인가

Playwright MCP(Model Context Protocol) 서버는 Claude AI가 웹 브라우저를 직접 제어하고 자동화할 수 있게 해주는 도구입니다. 일반적으로 Claude는 텍스트 기반 작업만 가능했지만, Playwright MCP 서버를 연결하면 웹페이지 클릭, 폼 입력, 스크린샷 촬영, 데이터 스크래핑 등의 실제 브라우저 작업을 자동으로 처리할 수 있습니다. 이를 통해 웹 사이트 테스트 자동화, 정보 수집, 반복적인 웹 작업 자동화 등이 가능해집니다.

사전 요구사항 및 환경 설정

Playwright MCP 서버를 Claude Desktop에 연결하기 위해서는 먼저 몇 가지 필수 프로그램을 설치해야 합니다. Node.js 18.0 이상이 설치되어 있어야 하며, npm 패키지 관리자도 함께 제공됩니다. 또한 Claude Desktop 애플리케이션 자체도 최신 버전으로 업데이트되어 있어야 합니다. 운영체제는 Windows, macOS, Linux 모두 지원하며, 인터넷 연결이 필요합니다.

먼저 Node.js가 설치되어 있는지 확인합니다:

node --version
npm --version

위 명령어 실행 시 버전 정보가 표시되면 설치되어 있는 것입니다. Node.js가 없다면 https://nodejs.org에서 LTS 버전을 다운로드하여 설치합니다.

Playwright MCP 서버 설치

Claude Desktop에서 Playwright MCP 서버를 사용하기 위해서는 npm을 통해 패키지를 설치해야 합니다. 터미널을 열고 다음 명령어를 실행합니다:

npm install -g @modelcontextprotocol/server-playwright

설치가 완료되었는지 확인하려면 다음 명령어를 실행합니다:

playwright --version

정상적으로 설치되었다면 버전 번호가 출력됩니다. 만약 "command not found" 오류가 나면 npm의 global 디렉토리가 PATH에 포함되지 않은 것일 수 있습니다. Windows의 경우 npm prefix 경로를 PATH에 추가해야 합니다:

npm config get prefix

출력된 경로를 Windows 환경변수 PATH에 추가합니다.

Claude Desktop 설정 파일 구성

Claude Desktop이 Playwright MCP 서버를 인식하고 사용하려면 설정 파일을 수정해야 합니다. Claude Desktop의 설정 파일은 운영체제별로 다른 위치에 있습니다.

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

해당 경로로 이동하여 claude_desktop_config.json 파일을 텍스트 에디터로 열거나, 파일이 없다면 새로 생성합니다. 다음과 같은 구조의 JSON 파일을 작성합니다:

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": [
        "-m",
        "@modelcontextprotocol/server-playwright"
      ]
    }
  }
}

이 설정은 Claude Desktop에게 Playwright MCP 서버를 Node.js 환경에서 실행하라고 지시합니다. 파일을 저장한 후 Claude Desktop을 완전히 종료했다가 다시 시작합니다. 정상적으로 설정되었다면 Claude와의 대화 창에 새로운 도구 아이콘이 나타날 것입니다.

Playwright MCP 서버 활성화 확인

Claude Desktop을 재시작한 후 새로운 대화를 시작하면 Playwright MCP 서버가 활성화되었는지 확인할 수 있습니다. 대화 입력창 아래에 사용 가능한 도구 목록이 표시됩니다. Playwright 관련 도구들이 보이면 설정이 성공한 것입니다.

다음과 같이 간단하게 테스트해봅니다:

구글 홈페이지로 이동해서 스크린샷을 찍어줄래?

Claude가 자동으로 브라우저를 열고 구글 홈페이지에 접속한 후 스크린샷을 촬영합니다. 이 과정에서 실시간으로 브라우저 창이 화면에 나타나고, Claude가 수행한 동작들이 기록됩니다.

실전 예제 1: 웹페이지 자동 스크래핑

실제로 웹사이트에서 정보를 자동으로 수집하는 예제를 진행합니다. 특정 뉴스 사이트에서 기사 제목들을 수집하고 정리하는 작업을 Claude에게 지시합니다:

Hacker News(https://news.ycombinator.com)의 최신 기사 제목 10개를 모두 수집해서 마크다운 형식의 리스트로 정렬해줄래?

Claude는 다음과 같은 순서로 작업을 수행합니다: 브라우저에서 해당 URL로 이동 → 페이지 로딩 대기 → 기사 제목 요소 찾기 → 텍스트 추출 → 정렬 및 포맷팅. 작업이 완료되면 마크다운 형식의 리스트가 표시됩니다.

실전 예제 2: 로그인 및 폼 자동 입력

많은 웹사이트에서는 로그인이 필요합니다. Playwright MCP를 사용하면 자동으로 로그인하고 필요한 정보를 입력할 수 있습니다. 실제 자격증명을 직접 입력하는 대신, 환경변수에서 읽도록 설정하는 것이 보안상 좋습니다:

# Linux/macOS
export GITHUB_USERNAME="your_username"
export GITHUB_PASSWORD="your_password"

# Windows PowerShell
$env:GITHUB_USERNAME="your_username"
$env:GITHUB_PASSWORD="your_password"

Claude는 이 환경변수를 읽어 자동으로 로그인하고 검색을 수행합니다. 작업 완료 후 결과를 텍스트로 반환합니다.

실전 예제 3: 다중 페이지 네비게이션

복잡한 웹사이트에서 여러 페이지를 순회하며 데이터를 수집하는 작업도 가능합니다. 예를 들어 이커머스 사이트에서 상품을 검색하고 여러 페이지를 넘어다니며 가격 정보를 수집합니다:

다음 작업을 1번부터 10번까지 반복해줄래:
1. 이 URL로 이동
2. 검색어를 입력
3. 검색 실행
4. 결과의 제목과 가격 추출
5. CSV 형식으로 기록

트러블슈팅: 자주 발생하는 오류와 해결법

오류 1: "command not found: playwright"

npm 패키지가 제대로 설치되지 않았거나 PATH가 설정되지 않은 경우입니다:

# npm 전역 설치 경로 확인
npm config get prefix

# .bashrc 또는 .zshrc에 다음 추가:
export PATH="$(npm config get prefix)/bin:$PATH"

# 변경 사항 적용
source ~/.bashrc

오류 2: "Failed to launch browser"

Playwright가 시스템 브라우저를 찾지 못한 경우입니다. Chromium, Firefox, WebKit을 설치합니다:

playwright install

오류 3: "MCP Server not responding"

Claude Desktop의 설정 파일이 올바르지 않거나 서버가 정상 시작되지 않은 경우입니다:

# 설정 파일 문법 검증 (JSON 형식 확인)
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

오류 4: "Permission denied" 에러

# 파일 권한 확인 (macOS/Linux)
ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 필요시 권한 수정
chmod 644 ~/Library/Application\ Support/Claude/claude_desktop_config.json

고급 설정: 커스텀 브라우저 옵션

기본 설정 외에 추가적인 브라우저 옵션을 지정할 수 있습니다:

{
  "mcpServers": {
    "playwright": {
      "command": "node",
      "args": ["-m", "@modelcontextprotocol/server-playwright"],
      "env": {
        "PLAYWRIGHT_BROWSER_TYPE": "chromium",
        "PLAYWRIGHT_HEADLESS": "false"
      }
    }
  }
}

PLAYWRIGHT_HEADLESS 옵션을 "false"로 설정하면 브라우저 창이 화면에 표시되어 실시간으로 동작을 확인할 수 있습니다. "true"로 설정하면 백그라운드에서 숨겨진 상태로 실행되어 더 빠릅니다.

보안 고려사항

Playwright MCP를 사용할 때는 보안에 주의해야 합니다. 비밀번호나 API 키 같은 민감한 정보를 직접 프롬프트에 입력하지 않도록 합니다. 대신 환경변수나 .env 파일을 사용합니다. 스크린샷이나 추출된 데이터에 민감한 정보가 포함될 수 있으니, 특히 공개 채널이나 클라우드 저장소에 공유할 때는 민감한 데이터를 먼저 제거하도록 주의합니다.

결론 및 추가 학습

Playwright MCP 서버를 Claude Desktop에 연결하면 AI가 단순한 텍스트 처리를 넘어 실제 웹 브라우저 작업을 자동화할 수 있습니다. 설치부터 설정, 기본 사용, 고급 예제까지 이 글에서 다룬 내용을 차근차근 따라가면 자신의 필요에 맞는 웹 자동화 시스템을 구축할 수 있습니다.

더 자세한 정보는 공식 Playwright 문서와 Model Context Protocol 규격서를 참고하기 바랍니다. 커뮤니티 포럼과 GitHub 이슈 페이지에서도 다양한 예제와 해결책을 찾을 수 있습니다.

이 글에 소개된 서비스와 도구는 작성 시점 기준이며, 업데이트에 따라 변경될 수 있습니다.