Whale DevTools MCP

AI 코딩 어시스턴트(Claude, Cursor, Copilot 등)가 Naver Whale 브라우저를 직접 제어할 수 있게 해주는 MCP 서버입니다.

chrome-devtools-mcp의 브라우저 자동화, 디버깅, 성능 분석 기능을 모두 포함하며, 그 위에 Whale 고유의 확장 앱과 사이드바를 AI가 신속·정확하게 제어할 수 있는 기능을 추가로 제공합니다. Whale 확장/사이드바 개발 및 테스트 자동화에 특히 유용합니다.

Based on chrome-devtools-mcp by Google LLC (Apache 2.0).

설치 및 설정

npm 패키지: whale-devtools-mcp

Claude Code

claude mcp add whale-devtools -- npx -y whale-devtools-mcp@latest --channel=whale

Canary도 함께 사용한다면:

claude mcp add whale-devtools-canary -- npx -y whale-devtools-mcp@latest --channel=whale-canary

Claude Desktop / 기타 MCP 클라이언트

{
  "mcpServers": {
    "whale-devtools": {
      "command": "npx",
      "args": ["-y", "whale-devtools-mcp@latest", "--channel=whale"]
    }
  }
}

연결 방식

서버는 다음 순서로 Whale에 연결합니다.

1. 실행 중인 Whale 자동 감지 — 기본 포트(stable: 9222, Canary: 9223) 폴링
2. DevToolsActivePort 파일 확인 — whale://inspect 토글로 랜덤 포트가 할당된 경우
3. 자동 실행 — 실행 중인 인스턴스가 없으면 Whale을 직접 실행하고 연결

안정적인 연결을 위해 whale://inspect 토글보다 --remote-debugging-port 고정 포트 사용을 권장합니다.

연결 상태를 확인하려면 list_browser_targets 도구를 사용하세요.

기능 제한

사이드바 / 확장 앱 제어

사이드바 및 Whale 확장 앱 관련 도구(--category-extensions)는 is_dev_build=true인 개발용 빌드 또는 Whale Canary에서만 지원됩니다. 일반 Whale stable에서는 해당 기능이 동작하지 않습니다.

주요 CLI 옵션

| 옵션 | 설명 | |------|------| | --channel=whale | Whale stable 연결/실행 (기본값) | | --channel=whale-canary | Whale Canary 연결/실행 | | --executable-path=<path>, -e | 커스텀 Whale 바이너리 (예: 직접 빌드한 out/Release/whale.exe). WHALE_PATH 환경변수로도 지정 가능 | | --auto-connect | 실행 중인 Whale에만 연결 (자동 실행 안 함) | | --browserUrl=<url> | HTTP로 직접 연결 (예: http://127.0.0.1:9222) | | --wsEndpoint=<url> | WebSocket으로 직접 연결 | | --no-usage-statistics | 사용 통계 전송 비활성화 | | --no-performance-crux | CrUX API 연동 비활성화 |

커스텀 Whale 빌드 사용 예 (env)

직접 빌드한 Whale을 지정해 테스트하려면 WHALE_PATH 환경변수를 사용하세요. 명시적인 --executable-path가 항상 우선합니다.

{
  "mcpServers": {
    "whale-devtools-built": {
      "command": "npx",
      "args": ["-y", "whale-devtools-mcp@latest"],
      "env": {
        "WHALE_PATH": "D:\\DevProjects\\naverwhale3\\src\\out\\Release\\whale.exe"
      }
    }
  }
}

주의사항

• 이 MCP 서버는 브라우저의 페이지, 콘솔, 네트워크 정보를 AI 클라이언트에 노출합니다. 민감한 정보가 있는 브라우저에서는 주의하세요.
• 성능 도구는 기본적으로 페이지 URL을 Google CrUX API에 전송합니다. --no-performance-crux로 비활성화 가능합니다.

License

Apache License 2.0 — LICENSE

Based on chrome-devtools-mcp, Copyright 2025 Google LLC.
Modifications Copyright 2025 Naver Corp.