stealth-browser-mcp

AI 어시스턴트에게 로그인 상태가 유지되는 실제 Chrome 브라우저를 제공하는 MCP 서버입니다.

대부분의 브라우저 자동화 도구는 모델에게 새롭고 빈 브라우저를 제공합니다. 하지만 이 도구는 영구 Chrome 프로필을 구동하므로, 2FA, CAPTCHA 또는 기기 승인 등 사이트가 요구하는 모든 절차를 직접 통과하여 한 번 로그인하면, 모델은 이후 실행에서도 비밀번호를 노출하지 않고 해당 세션을 계속 사용할 수 있습니다.

스크립트 로그인을 허용하지 않는 사이트를 위해 두 가지 탈출구를 제공합니다: 입력 시점에 macOS 키체인에서 가져오는 자격 증명, 그리고 Chrome의 가상 인증기를 통해 재생되는 WebAuthn 패스키입니다.

[!WARNING] 이것은 강력한 도구입니다. 언어 모델에게 사용자의 실시간 세션을 보유한 브라우저의 제어권을 부여하며, 모델이 선택한 페이지에 저장된 비밀번호를 입력할 수 있습니다. 중요한 것을 대상으로 사용하기 전에 SECURITY.md와 책임 있는 사용을 읽으십시오.

목차

• 작동 방식

• 요구 사항

• 설치

• MCP 클라이언트에 연결

• 첫 로그인

• 도구 참조

• 키체인에 자격 증명 저장

• 패스키

• 구성

• 스텔스 검증

• 문제 해결

• 책임 있는 사용

• 라이선스

Related MCP server: agent-browser-mcp

작동 방식

        MCP client (Claude Code, Claude Desktop, Cursor, …)
                          │
                          │  JSON-RPC over stdio
                          ▼
              ┌───────────────────────────┐
              │   stealth-browser-mcp     │
              │   16 tools, one browser   │
              └─────┬───────────────┬─────┘
                    │               │
     credentials    │               │   CDP + Puppeteer
                    ▼               ▼
        ┌───────────────────┐   ┌───────────────────────┐
        │  macOS Keychain   │   │  Google Chrome        │
        │  stealth-mcp:*    │   │  + stealth plugin     │
        │  passwords,       │   │  + WebAuthn virtual   │
        │  passkey material │   │    authenticator      │
        └───────────────────┘   └───────────┬───────────┘
                                            │
                                            ▼
                              ┌─────────────────────────┐
                              │  Persistent profile dir │
                              │  cookies · localStorage │
                              │  IndexedDB · sessions   │
                              └─────────────────────────┘

세 가지 구성 요소가 작동합니다:

영속성. Chrome은 임시 디렉토리 대신 고정된 userDataDir로 실행됩니다. 한 번 대화형으로 로그인하면 쿠키가 이후 모든 실행에서 유지됩니다 — 실제 사이트에서 자동화가 실패하는 일반적인 원인이 사라집니다.

스텔스. puppeteer-extra-plugin-stealth가 잘 알려진 자동화 탐지 신호를 패치하고, 서버는 몇 가지를 추가로 적용합니다: navigator.webdriver는 undefined, window.chrome.runtime은 존재, HeadlessChrome은 사용자 에이전트에서 제거, --disable-blink-features=AutomationControlled 설정. 클릭은 대상 내부의 지터된 지점까지 마우스를 경로를 따라 이동시키며, 입력은 30–100ms 간격으로 문자 하나씩 수행됩니다.

세션 생성이 아닌 세션 재사용. 설계 목표는 로그인 자동화를 피하는 것입니다. 키체인 자동 입력과 패스키 재생은 불가피한 경우를 위해 존재합니다.

요구 사항

• Node.js 18 이상

• Google Chrome. Puppeteer에 번들된 Chromium도 작동하지만, 실제 Chrome 빌드가 탐지 가능성이 현저히 낮습니다.

• macOS — 키체인 및 패스키 기능을 원하는 경우. 그 외 모든 기능(탐색, 추출, 스크린샷, 영구 프로필)은 크로스 플랫폼입니다. 키체인 계층은 /usr/bin/security를 호출하므로 다른 플랫폼에서는 실패합니다. 브라우저 도구는 이를 사용하지 않습니다.

설치

git clone https://github.com/lauyuen/stealth-browser-mcp.git
cd stealth-browser-mcp
npm install

선택적으로 예제 환경 파일을 복사하고 편집합니다:

cp .env.example .env

브라우저가 실행되고 회피 기능이 활성화되었는지 확인합니다:

npm run check-stealth

MCP 클라이언트에 연결

서버는 stdio를 사용합니다. 절대 경로로 src/server.js를 클라이언트에 지정하십시오.

Claude Code

claude mcp add stealth-browser -- node /absolute/path/to/stealth-browser-mcp/src/server.js

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"]
    }
  }
}

기타 MCP 클라이언트 — 동일한 형식에 선택적 프로필 재정의 추가:

{
  "mcpServers": {
    "stealth-browser": {
      "command": "node",
      "args": ["/absolute/path/to/stealth-browser-mcp/src/server.js"],
      "env": {
        "BROWSER_PROFILE_DIR": "/absolute/path/to/a/private/profile/dir"
      }
    }
  }
}

이후 클라이언트를 다시 시작하십시오. browser_status가 연결 상태를 확인하는 가장 빠른 방법입니다.

첫 로그인

모델이 사이트를 사용하기 전에 프로필을 직접 시드하십시오:

npm run login -- https://example.com

MCP 서버가 사용할 동일한 프로필로 보이는 Chrome 창이 열립니다. 비밀번호 관리자, 2FA 프롬프트, CAPTCHA, "이 기기 기억하기" 등 모든 절차를 정상적으로 수행하여 로그인하십시오. 완료되면 터미널에서 Enter를 누르면 세션이 디스크에 저장됩니다.

이후 모든 MCP 실행은 해당 세션을 상속합니다. 사이트별로 반복하십시오. 세션은 사이트 자체 일정에 따라 만료되므로, 사이트가 로그아웃되면 이 과정을 다시 실행하십시오.

도구 참조

탐색 및 상호작용

페이지 읽기

세션 및 인증

브라우저 수명 주기

브라우저는 기본적으로 헤드리스로 실행되며 호출 간에 재사용됩니다. browser_open_interactive_window는 보이는 창으로 전환하는 유일한 도구입니다.

키체인에 자격 증명 저장

비밀번호는 stealth-mcp: 서비스 접두사로 macOS 키체인에 저장됩니다 — 이 저장소의 파일이나 모델의 컨텍스트에는 절대 저장되지 않습니다.

npm run keychain set github you@example.com     # prompts; input is not echoed
npm run keychain get github you@example.com     # confirms presence, prints length only
npm run keychain delete github you@example.com

그러면 모델은 비밀번호를 알지 못한 채 로그인을 트리거합니다:

// browser_autofill_login
{
  "service": "github",
  "account": "you@example.com",
  "usernameSelector": "#login_field",
  "passwordSelector": "#password",
  "submitSelector": "input[type='submit']"
}

service는 사용자가 선택하는 임의의 레이블입니다 — CLI와 도구 호출 간에 일치하기만 하면 됩니다.

스크립팅을 위해 비밀번호를 후행 CLI 인수로 전달할 수도 있지만, 셸 히스토리와 프로세스 목록에 남게 되므로 명령이 경고를 표시합니다.

패스키

Chrome은 DevTools 프로토콜을 통해 WebAuthn 가상 인증기를 노출합니다 — WebAuthn 흐름 테스트를 위한 소프트웨어 인증기입니다. 이 서버는 이를 구동하고 결과 키 자료를 키체인에 저장하여 실행 간에 유지되도록 합니다.

자동화 패스키 등록

1. 인수 없이 passkey_enable_virtual_authenticator 호출.

2. 사이트의 "패스키 추가" 흐름으로 이동하여 완료합니다. 가상 인증기가 챌린지에 응답하며 OS 프롬프트가 나타나지 않습니다.

3. 사이트의 rpId와 계정으로 passkey_save_registration 호출.

이후 사용

rpId와 account로 passkey_enable_virtual_authenticator를 호출하면 탐색 전에 저장된 자격 증명이 주입되고, 사이트는 프롬프트 없이 로그인을 완료합니다.

[!CAUTION] 이렇게 보관된 패스키는 하드웨어 키가 아닌 파일입니다. 복사가 가능하며, 이는 실제 패스키가 방지하기 위해 존재하는 바로 그 속성입니다. 자동화 전용 패스키만 등록하십시오. 이메일, 은행 또는 분실 시 중대한 영향을 미치는 다른 것의 패스키에는 사용하지 마십시오.

구성

모든 설정은 환경 변수이며, 프로세스 환경 또는 .env 파일에서 읽습니다. .env.example을 참조하십시오.

Chrome 실행 플래그와 기본 1280×800 뷰포트는 src/config.js에 있습니다. 여러 플래그가 보안과 호환성을 맞바꿉니다 — SECURITY.md에서 어떤 플래그인지와 제거해야 하는 이유를 설명합니다.

스텔스 검증

npm run check-stealth

navigator.webdriver, window.chrome, window.chrome.runtime, 플러그인 수, navigator.languages 및 실제 사용자 에이전트를 보고한 다음, 확정된 프로필과 Chrome 경로를 출력합니다.

더 엄격한 확인을 위해 browser_navigate로 브라우저를 핑거프린팅 페이지(예: bot.sannysoft.com 또는 abrahamjuliot.github.io/creepjs)로 이동시킨 후 browser_screenshot을 호출하세요.

어떤 스텔스 설정도 감지되지 않을 수는 없습니다. 잘 방어된 사이트는 핑거프린팅을 행동 분석, IP 평판, 계정 이력과 결합하므로 여전히 자동화를 알아챌 수 있습니다. 이는 "명백한 검사를 유발하지는 않는다"는 의미이지, "완전히 감지되지 않는다"는 의미가 아닙니다.

문제 해결

"Failed to launch the browser process" / 프로필이 잠겨 있음. Chrome은 프로필 디렉터리당 하나의 프로세스만 허용합니다. 같은 디렉터리를 대상으로 수동으로 시작한 Chrome이 있다면 모두 닫으세요. 서버는 시작 시 오래된 Singleton* 잠금 파일을 정리하고 DevTools 포트를 통해 실행 중인 인스턴스에 다시 연결하지만, 프로필을 소유한 실행 중인 Chrome이 우선합니다.

사이트가 모델을 로그아웃시키거나 차단함. 저장된 세션이 만료된 것입니다. npm run login -- <url>을 다시 실행하세요.

선택자가 일치하지 않음. 좁은 선택자로 browser_extract_html을 호출해 모델이 추측하는 대신 실제 마크업을 읽게 하세요. 단일 페이지 앱은 입력 요소를 늦게 마운트하는 경우가 많으므로 먼저 browser_wait_for를 호출하세요.

CAPTCHA가 나타남. browser_open_interactive_window를 호출해 직접 해결한 다음 계속 진행하세요. 해결된 상태는 프로필에 유지됩니다.

Linux 또는 Windows에서 Keychain 오류. 예상된 동작입니다. 이 계층은 macOS 전용입니다. 브라우저 도구는 모든 플랫폼에서 작동하지만, 자격 증명 및 패스키 도구는 작동하지 않습니다.

책임 있는 사용

이 프로젝트는 어시스턴트가 사용자가 이미 계정을 보유한 사이트에서 사용자가 직접 설정한 세션을 사용해 작업할 수 있도록 하기 위해 존재합니다. 이것이 의도된 범위이며, 영구 프로필 설계도 이를 반영합니다.

안티 탐지 및 자격 증명 자동화는 분명히 다른 용도로 사용될 수 있습니다. 사이트에 적용하기 전에 다음을 고려하세요:

• 사이트의 서비스 약관. 많은 사이트가 자동화된 접근을 명시적으로 금지합니다. 봇 방어를 우회하는 것은 사용자가 체결한 계약을 위반하는 것일 수 있으며, 일부 관할권에서는 무단 접근이 형사 책임을 수반합니다. 통제를 우회할 수 있다는 것은 그렇게 할 권한이 있다는 뜻이 아닙니다.

• 동의. 자신의 계정 또는 서면으로 승인받은 계정만 자동화하세요. 다른 사람의 자격 증명이 Keychain에 있다는 것은 동의가 아닙니다.

• 부하. 요청 속도를 제한하세요. 적용되는 곳에서는 robots.txt를 준수하세요. 사이트에 실제 비용을 발생시키는 자동화는 이 기법이 모두에게 금지되는 지름길입니다.

• 타인의 데이터. 모델이 읽는 페이지는 MCP 클라이언트의 제공자로 전달됩니다. 제3자의 개인 정보를 이 경로로 흘려보내지 마세요.

특정 사이트의 보호 조치를 무력화하거나, 자격 증명을 수집하거나, 남용을 확대하는 것을 주된 목적으로 하는 기여는 병합되지 않습니다.

라이선스

MIT © Yuen Lau