Claude Desktop에 Playwright MCP 서버 연결해서 웹 자동화하기 — 설치부터 실전 스크립트까지

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

Claude AI가 점점 더 강력해지면서, 단순한 텍스트 응답을 넘어 실제 웹 브라우저를 제어할 수 있게 되었습니다. 이를 가능하게 하는 핵심 기술이 바로 Playwright MCP(Model Context Protocol)입니다. 이 글에서는 Claude Desktop 환경에서 Playwright MCP를 직접 설치하고 설정하는 전체 과정을 다룹니다. 초기 환경 확인부터 실제 웹 자동화 스크립트 실행, 그리고 발생할 수 있는 문제 해결까지 단계별로 진행하겠습니다.

1단계: Node.js 설치 확인 및 환경 점검

Node.js가 설치되어 있는지 확인하기

Playwright MCP는 Node.js 기반이므로, 가장 먼저 Node.js가 설치되어 있는지 확인해야 합니다. 터미널을 열고 다음 명령어를 실행하세요:

node --version
npm --version

정상적으로 설치되었다면 다음과 같은 출력이 나타납니다:

v20.11.0
10.5.0

Node.js 설치가 필요한 경우

만약 Node.js가 설치되지 않았다면, 공식 웹사이트(nodejs.org)에서 LTS 버전을 다운로드하여 설치하세요. 설치 후 터미널을 재시작하고 다시 버전을 확인하면 정상 작동을 확인할 수 있습니다.

npx 명령어 확인

Playwright MCP를 설치할 때 npx 명령어를 사용합니다. npm을 설치하면 자동으로 포함되므로, 별도의 설치는 필요 없습니다:

npx --version

2단계: Playwright MCP 패키지 설치

npm으로 Playwright MCP 설치하기

Playwright MCP를 설치하는 가장 표준적인 방법은 npm 패키지 매니저를 사용하는 것입니다. 다음 명령어를 실행하세요:

npm install -g @anthropic-ai/playwright-mcp

이 명령어는 Playwright MCP를 전역으로 설치합니다. -g 플래그는 "global"을 의미하며, 시스템 어디서나 해당 패키지를 사용할 수 있게 해줍니다.

설치 완료 확인

설치가 완료되었는지 확인하려면, 설치된 전역 패키지 목록을 확인하세요:

npm list -g @anthropic-ai/playwright-mcp

정상적으로 설치되었다면 다음과 같은 출력이 나타납니다:

/usr/local/lib/node_modules/@anthropic-ai/playwright-mcp
├── version: 1.0.0
└── dependencies...

설치 경로 확인

Playwright MCP가 설치된 정확한 경로가 필요할 수 있습니다. 다음 명령어로 확인하세요:

npm config get prefix

이 명령어는 전역 npm 패키지가 설치되는 기본 경로를 보여줍니다. 일반적으로 macOS에서는 /usr/local 또는 ~/.nvm/versions/node이고, Linux에서는 /usr/local입니다.

3단계: Claude Desktop 설정 파일 수정

claude_desktop_config.json 파일 위치

Claude Desktop이 MCP 서버를 인식하려면 설정 파일을 수정해야 합니다. 설정 파일의 위치는 운영 체제에 따라 다릅니다:

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

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

설정 파일 열기 및 편집

텍스트 에디터를 사용하여 설정 파일을 엽니다. 예를 들어, macOS에서는:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

또는 명령어 라인 에디터 nano를 사용할 수 있습니다:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

MCP 서버 설정 추가

설정 파일을 열면 다음과 같은 JSON 구조가 보일 것입니다:

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

만약 파일이 비어 있거나 mcpServers 섹션이 없다면, 위의 구조를 추가해야 합니다. 파일 전체 구조는 다음과 같아야 합니다:

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

설정 파일 저장 및 확인

편집을 완료한 후 파일을 저장합니다. nano 에디터를 사용한 경우, Ctrl+X를 누르고 Y로 저장을 확인한 후 Enter를 누르면 됩니다.

설정이 올바르게 입력되었는지 JSON 문법을 확인하세요. JSON 형식이 잘못되면 Claude Desktop이 제대로 인식하지 못합니다:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

jq 명령어가 없으면 다음과 같이 설치할 수 있습니다:

brew install jq

4단계: Claude Desktop 재시작 및 MCP 서버 연결 확인

Claude Desktop 종료 및 재시작

설정 파일을 수정한 후에는 Claude Desktop을 완전히 종료했다가 다시 시작해야 합니다. 단순히 창을 닫는 것이 아니라 애플리케이션을 완전히 종료해야 합니다:

killall "Claude"

그 다음 Claude Desktop을 다시 열면, 새로운 설정을 읽고 MCP 서버를 초기화합니다.

MCP 연결 상태 확인

Claude Desktop이 정상적으로 MCP 서버에 연결되었는지 확인하는 방법은 여러 가지가 있습니다. Claude와의 대화에서 직접 웹 자동화 요청을 해보는 것이 가장 간단합니다.

Claude와의 새로운 대화창에서 다음과 같이 물어볼 수 있습니다:

"저는 현재 playwright-mcp가 연결되어 있나요? 확인해주세요."

만약 Playwright가 정상적으로 연결되었다면, Claude는 웹 브라우저를 제어할 수 있는 도구 모음에 접근할 수 있을 것입니다.

연결 실패 시 로그 확인

MCP 서버가 제대로 연결되지 않았다면, Claude Desktop의 로그를 확인하세요:

tail -f ~/Library/Logs/Claude/claude.log

이 명령어는 실시간으로 Claude의 로그를 표시하므로, 어떤 오류가 발생했는지 확인할 수 있습니다.

5단계: 실전 웹 자동화 예시

예시 1: 웹사이트 스크린샷 캡처

Playwright MCP를 사용하여 웹사이트의 스크린샷을 자동으로 캡처할 수 있습니다. Claude에게 다음과 같이 요청할 수 있습니다:

"https://example.com 웹사이트의 스크린샷을 찍어줄 수 있나요?"

Claude는 이 요청을 받으면 Playwright를 통해 브라우저를 열고, 해당 URL로 이동한 후, 스크린샷을 촬영합니다. 이 과정은 모두 자동으로 이루어집니다.

예시 2: 자동 로그인 및 데이터 수집

더 복잡한 예시로, 특정 웹사이트에 로그인한 후 데이터를 수집하는 시나리오를 생각해봅시다. 다음은 이런 작업을 수행하기 위한 자동화 스크립트의 개념입니다:

const { chromium } = require('playwright');

async function loginAndCollectData() {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  // 웹사이트로 이동
  await page.goto('https://example.com/login');

  // 아이디 입력
  await page.fill('input[name="username"]', 'your_username');

  // 비밀번호 입력
  await page.fill('input[name="password"]', 'your_password');

  // 로그인 버튼 클릭
  await page.click('button[type="submit"]');

  // 로그인 완료 대기
  await page.waitForNavigation();

  // 데이터 수집
  const data = await page.evaluate(() => {
    return Array.from(document.querySelectorAll('.data-item')).map(el => el.textContent);
  });

  console.log('수집된 데이터:', data);

  await browser.close();
}

loginAndCollectData();

예시 3: 폼 자동 입력 및 제출

웹 폼을 자동으로 입력하고 제출하는 작업도 Playwright로 쉽게 처리할 수 있습니다:

const { chromium } = require('playwright');

async function fillAndSubmitForm() {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await page.goto('https://example.com/contact');

  // 이름 입력
  await page.fill('input#name', 'John Doe');

  // 이메일 입력
  await page.fill('input#email', 'john@example.com');

  // 메시지 입력
  await page.fill('textarea#message', '이것은 자동으로 입력된 메시지입니다.');

  // 라디오 버튼 선택
  await page.click('input[value="option1"]');

  // 체크박스 선택
  await page.check('input[type="checkbox"]');

  // 드롭다운 선택
  await page.selectOption('select#country', 'KR');

  // 폼 제출
  await page.click('button[type="submit"]');

  // 제출 완료 대기
  await page.waitForNavigation();

  console.log('폼이 성공적으로 제출되었습니다.');

  await browser.close();
}

fillAndSubmitForm();

예시 4: 동적 콘텐츠 대기 및 수집

많은 현대 웹사이트는 JavaScript로 콘텐츠를 동적으로 로드합니다. 이 경우 특정 요소가 나타날 때까지 기다려야 합니다:

const { chromium } = require('playwright');

async function waitForDynamicContent() {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await page.goto('https://example.com');

  // 특정 요소가 나타날 때까지 대기 (최대 10초)
  await page.waitForSelector('.dynamic-content', { timeout: 10000 });

  // 모든 동적 콘텐츠 수집
  const dynamicData = await page.evaluate(() => {
    const elements = document.querySelectorAll('.dynamic-item');
    return Array.from(elements).map(el => ({
      title: el.querySelector('.title')?.textContent,
      description: el.querySelector('.description')?.textContent
    }));
  });

  console.log('동적 콘텐츠:', dynamicData);

  await browser.close();
}

waitForDynamicContent();

6단계: Claude와 상호작용하며 웹 자동화하기

Claude에게 웹 자동화 작업 요청하기

Playwright MCP가 제대로 설정되면, Claude와 자연스럽게 대화하면서 웹 자동화 작업을 수행할 수 있습니다. 다음과 같은 요청을 할 수 있습니다:

요청 예시:

"https://news.example.com에서 최신 뉴스 제목들을 모두 수집해줄 수 있나요?"

Claude의 응답: Claude는 이 요청을 받으면, Playwright를 통해 브라우저를 열고, 해당 페이지로 이동하여, JavaScript를 사용해 모든 뉴스 제목을 추출합니다. 그리고 추출된 데이터를 정렬하여 보여줍니다.

단계별 지시사항 제공하기

더 복잡한 작업의 경우, Claude에게 단계별 지시사항을 제공할 수 있습니다:

"다음 순서대로 작업해줄 수 있나요? 1. https://example.com/search로 이동 2. 검색창에 '파이썬'을 입력 3. 검색 버튼 클릭 4. 검색 결과 페이지에서 결과 개수를 세기 5. 스크린샷 찍기"

반복적인 작업 자동화

Claude는 같은 작업을 여러 번 반복하도록 요청받을 수도 있습니다:

"다음 URL들에서 각각 스크린샷을 찍어줄 수 있나요? - https://example1.com - https://example2.com - https://example3.com"

Claude는 이 요청을 받으면 세 개의 URL을 모두 방문하여 각각 스크린샷을 촬영하고 저장합니다.

7단계: 트러블슈팅 및 문제 해결

문제 1: 포트 충돌 오류

증상: "Port 8080 is already in use" 또는 유사한 포트 충돌 오류가 발생합니다.

해결 방법: 먼저 해당 포트를 사용 중인 프로세스를 찾으세요:

lsof -i :8080

포트를 사용 중인 프로세스를 종료하거나, Playwright MCP 설정에서 다른 포트를 지정할 수 있습니다:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/playwright-mcp", "--port", "8081"]
    }
  }
}

문제 2: 권한 오류 (Permission Denied)

증상: "Permission denied" 오류가 발생하며 Playwright가 실행되지 않습니다.

해결 방법: 브라우저 실행 권한을 확인하고, 필요하면 권한을 조정합니다:

sudo chmod +x /usr/local/lib/node_modules/@anthropic-ai/playwright-mcp/bin/playwright

또는 설정에서 headless 모드를 명시적으로 설정합니다:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/playwright-mcp", "--headless"]
    }
  }
}

문제 3: 모듈을 찾을 수 없음 (Module not found)

증상: "Cannot find module '@anthropic-ai/playwright-mcp'" 오류가 발생합니다.

해결 방법: 먼저 Playwright MCP가 올바르게 설치되었는지 확인하세요:

npm list -g @anthropic-ai/playwright-mcp

설치되지 않았다면 다시 설치합니다:

npm install -g @anthropic-ai/playwright-mcp

설치 후에는 Claude Desktop을 반드시 재시작해야 합니다.

문제 4: Claude Desktop이 MCP 서버를 인식하지 못함

증상: Claude와 대화할 때 Playwright 도구를 사용할 수 없습니다.

해결 방법:

1. 설정 파일의 JSON 문법을 다시 확인합니다:

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

2. 설정 파일의 경로가 정확한지 확인합니다. 운영 체제에 맞는 올바른 경로를 사용했는지 다시 확인하세요.

3. Claude Desktop을 완전히 종료하고 다시 시작합니다:

killall "Claude"

4. Claude Desktop의 설정 메뉴에서 MCP 서버 상태를 확인합니다. 일부 Claude 버전에서는 설정 페이지에서 연결된 MCP 서버 목록을 볼 수 있습니다.

문제 5: 브라우저 크래시 또는 타임아웃

증상: 웹 자동화 작업 중 브라우저가 예상치 못하게 종료되거나 타임아웃이 발생합니다.

해결 방법: 타임아웃 값을 증가시키고, 필요시 대기 시간을 추가합니다:

const { chromium } = require('playwright');

async function robustNavigation() {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  // 타임아웃을 30초로 설정
  page.setDefaultTimeout(30000);
  page.setDefaultNavigationTimeout(30000);

  try {
    await page.goto('https://example.com', { waitUntil: 'networkidle' });
    // 작업 수행
  } catch (error) {
    console.error('오류 발생:', error);
  } finally {
    await browser.close();
  }
}

robustNavigation();

문제 6: DNS 또는 네트워크 오류

증상: 특정 웹사이트에 접근할 수 없거나 DNS 해석 오류가 발생합니다.

해결 방법: 네트워크 연결을 확인하고, 필요시 프록시 설정을 추가합니다:

const { chromium } = require('playwright');

async function withProxy() {
  const browser = await chromium.launch({
    proxy: {
      server: 'http://proxy.example.com:8080'
    }
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');

  await browser.close();
}

withProxy();

8단계: 고급 설정 및 최적화

환경 변수 설정

Playwright MCP의 동작을 세밀하게 조정하기 위해 환경 변수를 설정할 수 있습니다:

export DEBUG=pw:api
export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=0

Claude Desktop 설정에서 이러한 환경 변수를 명시적으로 설정할 수도 있습니다:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/playwright-mcp"],
      "env": {
        "DEBUG": "pw:api",
        "PLAYWRIGHT_HEADLESS": "true"
      }
    }
  }
}

성능 최적화

대량의 웹 자동화 작업을 수행할 때 성능을 최적화하려면:

const { chromium } = require('playwright');

async function optimizedBrowserOperation() {
  const browser = await chromium.launch({
    // GPU 가속 활성화
    args: ['--disable-dev-shm-usage', '--enable-gpu'],
    headless: true
  });

  const context = await browser.newContext({
    // 이미지 로딩 비활성화 (텍스트만 필요할 때)
    extraHTTPHeaders: {},
    javaScriptEnabled: true
  });

  const page = await context.newPage();

  // 작업 수행

  await browser.close();
}

optimizedBrowserOperation();

보안 설정

민감한 정보를 다루는 자동화 작업의 경우, 보안을 강화해야 합니다:

const { chromium } = require('playwright');

async function secureOperation() {
  const browser = await chromium.launch({
    headless: true,
    // 샌드박스 활성화
    args: ['--enable-features=NetworkService,NetworkServiceInProcess']
  });

  const context = await browser.newContext({
    // 쿠키 및 저장소 격리
    storageState: undefined,
    ignoreHTTPSErrors: false
  });

  const page = await context.newPage();

  // 작업 수행 시 민감한 정보는 로그하지 않기

  await browser.close();
}

secureOperation();

결론

이 글에서는 Claude Desktop에 Playwright MCP를 설치하고 설정하는 전체 과정을 다루었습니다. 초기 환경 확인부터 시작하여 패키지 설치, 설정 파일 수정, 실제 사용 예시, 그리고 문제 해결까지 모든 단계를 상세히 설명했습니다.

이제 여러분은 Claude를 통해 강력한 웹 자동화 작업을 수행할 수 있게 되었습니다. 로그인 자동화부터 데이터 수집, 폼 입력 등 다양한 웹 작업을 Claude의 도움으로 자동으로 처리할 수 있습니다. 초기 설정이 조금 복잡할 수 있지만, 한 번 설정을 완료하면 매우 강력한 도구를 손에 얻게 됩니다.

웹 자동화 작업을 하면서 새로운 문제에 직면한다면, 위의 트러블슈팅 섹션을 참고하거나 Playwright 공식 문서를 확인하세요. 그리고 Claude와의 상호작용을 통해 각 상황에 맞는 최적의 해결책을 찾을 수 있을 것입니다.

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