Skip to main content
Glama
compnew2006

Browser Controller

by compnew2006

이 프로젝트가 해결하는 문제

수정 사항을 배포했습니다. 에이전트가 "완료했습니다. 확인해 주세요."라고 말합니다. 여러분은 Chrome으로 알트탭을 하고, 페이지로 이동하고, 로그인하고, 클릭하며 버그를 찾습니다.

에이전트가 방금 코드를 작성했습니다. 에이전트가 검증할 수도 있습니다. 여러분의 브라우저가 이미 열려 있는데, 에이전트는 그걸 볼 수 없을 뿐입니다.

이제 볼 수 있습니다. Browser Controller는 MCP 호환 AI 에이전트(Cursor, Claude Desktop, Windsurf 등)에게 이미 열려 있는 브라우저를 직접 제어할 수 있게 해 줍니다 — 여러분의 실제 세션, 로그인, 쿠키까지. 헤드리스 브라우저도, 새 프로필도, 재인증도 필요 없습니다.

Related MCP server: Tabryn

주요 기능

  • 동시에 여러 에이전트. Cursor는 탭 10을, Claude는 탭 11을 제어할 수 있습니다 — 하나의 공유 데몬을 통해 서로를 막지 않습니다.

  • "활성 탭"이 아닌 탭 타게팅. 모든 액션은 tabId를 지정합니다. 마우스를 움직이고, 탭을 전환하고, YouTube를 봐도 에이전트는 여러분이 지정한 탭에서 계속 작업합니다. 여러분이 읽고 있는 페이지를 가로채지 않습니다.

  • 탭별 격리. 요소 참조, 콘솔 로그, 네트워크 버퍼는 탭별로 범위가 지정됩니다. 탭 10의 참조가 탭 20의 무언가를 클릭할 수 없습니다.

  • 탭별 동시성. 같은 탭에 대한 두 액션은 직렬화되고(경합 없음), 다른 탭에 대한 액션은 병렬로 실행됩니다.

  • 탭 잠금. 에이전트가 탭을 점유하면 다른 에이전트는 경합 대신 뒤에서 대기합니다(browser_tabs { action: "lock" }). 잠금은 Chrome의 서비스 워커 재활용(chrome.storage.session)을 넘어서도 유지됩니다.

  • 에이전트 제어 실드. 에이전트가 탭에서 작업하는 동안 반투명 파란색 내부 프레임이 표시되고 해당 탭에서의 입력(마우스, 키보드, 휠)이 차단됩니다 — 배지에 agent <name> controlling the tab이 표시되고 액션이 끝나면 사라집니다. 탭을 잠그면 잠금 기간 동안 일반 프레임이 유지됩니다.

  • 동일 출처 iframe 관통. iframe 안에 있는 레거시/엔터프라이즈 UI(예: iframe#mainFrame 안의 ONT 콘솔)에 접근할 수 있습니다: 모든 로케이터 도구가 iframe 문서를 검색하고, find/click_text는 모든 프레임을 탐색합니다.

  • 열린 대화상자 구조. 네이티브 alert/confirm/prompt는 페이지의 JS 스레드를 멈춥니다 — browser_handle_dialog가 CDP를 통해 대역 외로 이를 해제하며, 페이지 JS가 필요 없고 해당 탭의 다른 모든 도구도 차단 해제됩니다. browser_tabs close/focus는 탭이 멈춰 있어도 항상 작동합니다.

  • 인증된 로컬 연결. 토큰 + 일회성 등록 비밀번호로 다른 로컬 프로세스가 여러분의 브라우저를 조용히 제어할 수 없습니다. 모든 것이 localhost에 유지됩니다 — 클라우드도, 텔레메트리도 없습니다.

  • 디버거 배너 없음. browser_evaluatechrome.scripting을 통해 페이지의 MAIN 세계에서 실행됩니다 — 노란색 "이 탭이 디버깅 중입니다" 배너가 없고, 실제 값이 MV3 세계 경계를 넘어 반환됩니다.

  • 정직한 오류. 모든 도구 실패는 전체 페이로드와 함께 실제 isError 결과로 에이전트에게 전달됩니다 — 작업 흐름 중간에 실패를 숨기는 "성공" 응답이 없습니다.


작동 방식

세 가지 구성 요소, 모두 여러분의 머신에 있습니다. 아무것도 localhost를 벗어나지 않습니다.

  Agent (Cursor / Claude / Windsurf)        ── other agents connect too ──┐
                  │ stdio (MCP protocol)                                   │
                  ▼                                                        ▼
  ┌─────────────────────────────┐   ┌─────────────────────────────────────────┐
  │  thin MCP client            │   │  thin MCP client                        │
  │  (node mcp-server/dist/     │   │  (node mcp-server/dist/                 │
  │   index.js)                 │   │   index.js)                             │
  │  - speaks MCP over stdio    │   │  - spawns daemon if not running         │
  │  - forwards calls to daemon │   │  - gets its own sessionId               │
  └──────────────┬──────────────┘   └────────────────────┬───────────────────┘
                 │ local IPC socket (AF_UNIX / named pipe, token-auth)     │
                 ▼                                                          ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  DAEMON (single long-running process, owns port 7225)                     │
  │  - multiplexes N clients → 1 extension                                    │
  │  - tags every call with the client's sessionId                            │
  │  - heartbeat eviction, per-session rate limiting                          │
  └──────────────────────────────┬───────────────────────────────────────────┘
                                 │ WebSocket ws://127.0.0.1:7225 (token-auth)
                                 ▼
  ┌──────────────────────────────────────────────────────────────────────────┐
  │  Chrome Extension (Manifest V3 service worker)                            │
  │  - resolves the target tabId (never "the active tab" implicitly)          │
  │  - serializes same-tab actions, parallelizes cross-tab actions            │
  │  - executes click/type/snapshot/evaluate against the named tab            │
  └──────────────────────────────────────────────────────────────────────────┘

핵심 아이디어: 에이전트가 처음 실행되면 씬 클라이언트가 포트 7225와 확장 프로그램 연결을 소유하는 백그라운드 데몬을 생성합니다. 이후의 모든 에이전트(다른 MCP 클라이언트에서도)는 로컬 IPC 소켓을 통해 같은 데몬에 연결되고 고유한 sessionId를 받습니다. 확장 프로그램은 하나의 안정적인 연결을 보고 각 호출을 호출자가 지정한 정확한 탭으로 라우팅합니다.


빠른 시작

이 프로젝트는 Chrome Web Store나 npm에 없습니다 — 이 저장소에서 설치합니다. 두 부분으로 구성됩니다: MCP 서버(여러분의 머신에서 실행되며 AI 에이전트와 통신)와 Chrome 확장 프로그램(브라우저에 위치하며 명령을 실행).

사전 요구 사항: Node.js ≥ 20 및 Chrome/Chromium/Edge.

1. 클론 및 빌드

git clone https://github.com/compnew2006/browser-controller.git
cd browser-controller
npm install
npm run build        # compiles TypeScript → mcp-server/dist/

2. Chrome 확장 프로그램 로드

  1. chrome://extensions를 열고 개발자 모드를 활성화합니다(오른쪽 상단 토글)

  2. 압축 해제된 확장 프로그램 로드를 클릭하고 클론한 저장소의 extension/ 폴더를 선택합니다

  3. Browser Controller 아이콘을 툴바에 고정합니다

회색 점 = 데몬 대기 중. 녹색 = 연결됨.

3. MCP 서버를 클라이언트에 추가

Cursor: Settings → MCP → "Add new MCP server". Claude Desktop: claude_desktop_config.json 편집. Windsurf: Settings → MCP. MCP 호환 클라이언트라면 모두 작동합니다.

/path/to/browser-controller를 클론의 절대 경로로 바꿉니다(Windows: C:\\path\\to\\browser-controller\\mcp-server\\dist\\index.js 사용):

{
  "mcpServers": {
    "browser-controller": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"]
    }
  }
}

기본적으로 데몬은 각 연결을 상위 IDE("Cursor", "Claude" 등)의 이름으로 지정합니다. 재정의하려면 — 예를 들어 여러 에이전트가 하나의 IDE를 공유하거나 프로젝트별로 라벨을 붙이려면 — args에 --agent <name>을 전달하세요. 모든 자동 감지보다 우선합니다:

{
  "mcpServers": {
    "browser-controller": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js", "--agent", "My Project Agent"]
    }
  }
}

이름은 팝업의 연결된 에이전트 목록에 표시됩니다. (MCP_AGENT_NAME 환경 변수도 설정할 수 있습니다 — 동일합니다.) 같은 이름으로 다시 연결하면 기존 항목을 대체하므로 IDE를 재시작해도 중복이 쌓이지 않습니다.

4. 확장 프로그램을 데몬과 페어링

데몬은 두 개의 비밀번호를 사용하며, 둘 다 첫 실행 시 ~/.browser-controller/에 생성됩니다(Windows: %USERPROFILE%\.browser-controller\). 에이전트에게 "내 브라우저 탭 목록을 보여줘"라고 요청하여 한 번 시작한 다음:

  1. 비밀번호를 읽습니다:

    cat ~/.browser-controller/enrollment.json   # one-time pairing secret
    cat ~/.browser-controller/token.json        # WebSocket auth token

    (등록 비밀번호는 첫 실행 시 MCP 클라이언트 로그에도 출력됩니다.)

  2. 확장 프로그램 아이콘 클릭 → 설정 탭 → 등록 비밀번호인증 토큰을 붙여넣습니다(WS_PORT를 변경하지 않았다면 포트는 7225로 둡니다).

녹색 점 = 연결됨. 이제 에이전트가 여러분의 브라우저를 볼 수 있습니다.

이 비밀번호는 다른 로컬 프로세스가 WebSocket을 열어 인증된 브라우저 세션을 제어하는 것을 방지합니다. 교체하려면 MCP 클라이언트를 중지하고 폴더를 삭제하면 다음 실행 시 두 비밀번호가 모두 다시 생성됩니다. 전체 위협 모델은 SECURITY.md를 참조하세요.


사용 방법

모델은 탭 우선입니다: 에이전트는 항상 어느 탭에서 작업할지 말합니다. "활성 탭"을 가정하지 않습니다.

기본 워크플로

  1. 탭 목록을 가져와 tabId를 얻습니다:

    browser_tabs { action: "list" }
    → [{ id: 15, url: "...", title: "...", active: true, lockedBy: null }, ...]
  2. 해당 탭을 스냅샷하여 구조를 보고 요소 참조를 얻습니다:

    browser_snapshot { tabId: 15 }
    → { tree: [ { ref: "e3", role: "button", name: "Sign in" }, ... ] }

    참조는 이 tabId에만 유효합니다. 탐색하거나 DOM이 변경되면 다시 스냅샷하세요. 마지막 스냅샷 이후의 새 요소는 **isNew: true**로 표시됩니다 — 액션이 오버레이/드롭다운을 연 후 에이전트는 전체 트리를 다시 읽는 대신 그 요소들에만 집중할 수 있습니다.

  3. 참조와 같은 tabId를 사용하여 상호작용합니다:

    browser_click { tabId: 15, ref: "e3" }
    browser_type  { tabId: 15, ref: "e5", text: "hello@example.com" }
    browser_press_key { tabId: 15, key: "Enter" }

    참조가 오래되었지만 요소가 여전히 존재하면 강력한 선택자 + 텍스트/역할 스캔을 통해 자동으로 찾습니다(응답에 via: "fallback" 포함). 요소가 완전히 스크롤 밖으로 나간 경우(가상화된 피드), 응답에 **freshRefs: [...]**가 인라인 새 스냅샷과 함께 포함됩니다 — 별도의 스냅샷 없이 같은 단계에서 새 참조 중 하나로 재시도하세요.

  4. 검증 — 액션 후 다시 스냅샷하거나 텍스트를 읽습니다.

다중 에이전트 조정(두 에이전트, 두 탭)

  1. 에이전트 A가 탭 목록을 가져와 탭 10을 선택하고, 선택적으로 잠급니다: browser_tabs { action: "lock", tabId: 10 }

  2. 에이전트 B가 탭 목록을 가져와 탭 11을 선택하고 잠급니다: browser_tabs { action: "lock", tabId: 11 }

  3. 둘 다 병렬로 작업합니다. 각 에이전트의 호출은 자신의 탭에 대해 직렬화되고, 두 탭은 서로 간섭하지 않습니다.

  4. 완료 시: browser_tabs { action: "unlock", tabId: 10 }.

팝업은 여러분의 제어판입니다

고정 높이의 탭 셸(본문은 스크롤되지 않고 목록만 스크롤됩니다):

  • — 잠금 소유자가 있는 모든 열린 탭, 그리고 에이전트가 잠금 중간에 충돌한 경우 원클릭 해제를 위한 툴바의 모두 잠금 해제.

  • 에이전트 — 이름, 세션 ID, 가동 시간이 있는 각 연결된 에이전트, 그리고 즉시 연결을 끊는 ✕(하트비트가 아직 수거하지 못한 좀비를 정리).

  • 설정 — WebSocket 포트, 인증 토큰, 등록 비밀번호.

  • 활동 표시줄 — 하단의 접을 수 있는 스트립으로 최신 도구 활동을 표시합니다. 펼치면 롤링 로그가 보입니다.

알아두면 좋은 점

  • tabId를 잊으셨나요? 명확한 오류가 표시됩니다: tabId is required. Call browser_tabs list first.

  • 보호된 페이지(chrome://, Web Store, devtools)는 스크립팅할 수 없습니다 — 조용히 멈추는 대신 Cannot access protected page (chrome://...)가 표시됩니다.

  • **browser_navigate**tabId가 선택 사항인 유일한 도구입니다(기본값은 활성 탭) — 하지만 다중 에이전트 안전을 위해 명시적으로 전달하세요. 해시만 변경되는 경우(예: /page/page#section)는 complete 이벤트를 기다리지 않고 URL이 설정되는 즉시 해결됩니다(SPA는 해시 변경 시 리로드하지 않으므로 해당 이벤트가 발생하지 않습니다).

  • **browser_evaluate**는 페이지의 MAIN 세계에서 실행되며(디버거 배너 없음, CSP 안전) 실제 값을 반환합니다(세계 경계를 넘어 JSON 직렬화). 강력하지만 비멱등적입니다 — 시간 초과 시 자동 재시도되지 않습니다.

  • 가상화된 피드 스크롤(Facebook/Instagram/Twitter): browser_scroll은 해당 사이트가 DOM 노드를 재활용하므로 refsMayBeStale: true를 반환합니다. 다음 상호작용 전에 다시 스냅샷하세요.

  • 중복 요소: 여러 요소가 같은 텍스트+역할을 공유할 때(예: "좋아요" 버튼 3개), 폴백 해석기는 첫 번째 일치뿐만 아니라 서수(nth)로 올바른 요소를 선택합니다.

  • 멈춘 탭(네이티브 대화상자가 차단 중)은 교착 상태를 만들지 않습니다: browser_handle_dialog가 CDP를 통해 해제하고, browser_tabs { action: "close" }는 보장된 탈출구로 항상 작동합니다.


🧠 에이전트 교육

에이전트는 22개 도구를 모두 기본으로 사용할 수 있지만, 탭 우선 워크플로를 알면 더 잘 작동합니다. 저장소 루트에서:

npm run setup:cursor   # or: node mcp-server/dist/index.js --setup cursor

다음이 설치됩니다:

  • ~/.cursor/rules/browser-controller.mdc — 탭 타게팅 워크플로, 드롭다운 처리, 탭을 잠글 시점

  • ~/.cursor/commands/check-browser.md — Cursor 채팅에 /check-browser 추가

그 후 아무 채팅에서 /check-browser를 입력하세요. 또는 "내 브라우저에서 결과를 확인해 줘"라고 말하면 에이전트가 무엇을 해야 할지 압니다.

npm run setup:claude

프로젝트 루트에 AGENTS.md를 추가합니다. Claude Code가 자동으로 발견합니다.

수동 설치 또는 규칙 사용자 지정은 agent-config/를 참조하세요.


할 수 있는 일

22개 도구. 모든 페이지 상호작용 도구는 **tabId**를 받습니다(유일한 예외는 browser_navigate로, 선택 사항입니다).

보기

도구

기능

browser_snapshot

요소 참조가 포함된 접근성 트리. 컴팩트 모드(기본값)는 대화형 요소만 반환. shadow DOM 및 iframe을 탐색.

browser_screenshot

탭을 이미지로 캡처(먼저 탭을 활성화한 후 캡처)

browser_text

페이지 또는 요소에서 원시 텍스트 추출

browser_find

자연어로 요소 쿼리 — 동일 출처 iframe도 탐색

상호작용

도구

기능

browser_click

ref 또는 CSS 선택자로 클릭 — 동일 출처 iframe 관통

browser_click_text

표시된 텍스트로 클릭. React 포털 및 오버레이에서도 작동

browser_type

입력 필드 및 contenteditable 필드에 타이핑

browser_press_key

키 조합(Enter, Escape, Ctrl+A)

browser_scroll

페이지 및 가상 컨테이너 스크롤

browser_hover

툴팁 및 드롭다운 트리거

browser_select

기본 <select> 드롭다운에서 선택

browser_wait

요소가 나타나거나 사라질 때까지 대기

browser_fill_form

한 번의 호출로 여러 양식 필드 채우기(React/Vue 안전 setter)

browser_drag

요소 간 드래그(신뢰성을 위해 CDP 사용)

browser_upload_file

<input type="file">을 통해 파일 업로드(CDP 사용, strict-CSP 안전)

browser_upload_file은 사용자가 직접 선택한 것처럼 로컬 파일을 <input type="file">에 주입합니다. 네이티브 대화상자는 열리지 않으며, 이후 input/change 이벤트가 발생하여 React/Vue 양식이 반응합니다.

browser_upload_file { tabId: 15, selector: "#resume", filePath: "/Users/me/resume.pdf" }
browser_upload_file { tabId: 15, ref: "e12", files: ["/tmp/a.png", "/tmp/b.png"] }

경로는 절대 경로이며 브라우저가 실행 중인 머신에 로컬입니다. ref/selector를 생략하면 페이지의 첫 번째 파일 입력을 자동으로 대상으로 지정합니다. 여러 파일을 한 번에 업로드하려면 multiple 속성이 있는 입력이 필요합니다.

탐색

도구

기능

browser_navigate

탭에서 URL로 이동(tabId 선택 사항, 기본값은 활성 탭)

browser_tabs

탭 나열 / 생성 / 닫기 / 포커스 / 잠금 / 잠금 해제

디버그 및 고급

도구

기능

browser_console

콘솔 출력(log, warn, error) — 탭별, 최대 200개 항목

browser_network

상태 코드가 포함된 XHR/fetch 요청 — 탭별, 선택적 limit

browser_evaluate

페이지의 MAIN world에서 JavaScript 실행(배너 없음, CSP 안전)

browser_handle_dialog

CDP를 통해 열린 alert/confirm/prompt 닫기/수락(프리즈된 페이지에서도 작동)

browser_run_action

CDP를 통해 독립형 JS 액션 객체 실행


다른 도구와 비교

Browser Controller

Playwright MCP

Chrome DevTools MCP

기존 브라우저 사용

아니요, 새로 실행

부분적, 디버그 포트 필요

세션 및 쿠키

이미 있음

새 프로필

수동 설정

기업 SSO 뒤에서 작동

아니요

상황에 따라 다름

여러 에이전트, 여러 탭

아니요

아니요

탭 대상 지정(활성 탭을 가로채지 않음)

해당 없음

아니요

인증된 로컬 연결

해당 없음

아니요

설정

소스 빌드 + 확장 프로그램

헤드리스 브라우저

--remote-debugging-port가 있는 Chrome


구성

환경 변수

기본값

기능

WS_PORT

7225

데몬이 확장 프로그램 연결에 사용하는 WebSocket 포트

BROWSER_CONTROLLER_PROGRESSIVE

(설정 안 됨)

1로 설정하면 점진적 도구 공개가 활성화됩니다. 시작 시 browser_tools 메타 도구만 표시됩니다(전체 22개 정의의 약 4200토큰 대신 약 150토큰). 에이전트는 browser_tools {action:"list"/"search"}를 통해 도구를 발견하고 {action:"details", tool:"…"}로 활성화합니다. 기본값(설정 안 됨)은 모든 도구를 처음부터 표시합니다 — 도구를 직접 호출하도록 지시된 에이전트에게 안전합니다.

MCP_AGENT_NAME

(자동: IDE 이름)

팝업에 표시되는 에이전트 이름 재정의(--agent와 동일)

데몬 상태 파일

데몬은 모든 것을 ~/.browser-controller/에 보관합니다(Windows: %USERPROFILE%\.browser-controller\):

파일

용도

enrollment.json

확장 프로그램용 일회성 페어링 비밀(모드 0600)

token.json

확장 프로그램이 모든 WebSocket 연결에서 제시해야 하는 인증 토큰(모드 0600)

daemon.sock

씬 클라이언트가 연결하는 IPC 소켓(mac/linux의 AF_UNIX, Windows의 named pipe)

daemon.json

데몬 메타데이터(pid, 포트, 시작 시간) — 실행 중인 데몬 감지에 사용

daemon.log

클라이언트가 생성할 때의 데몬 stdout/stderr

완전히 초기화하려면: MCP 클라이언트를 중지하고 폴더를 삭제하면 다음 실행 시 새 비밀로 다시 생성됩니다.

안정성

  • 데몬은 클라이언트가 처음 실행될 때 자동으로 생성되며 분리된 상태로 계속 실행됩니다.

  • 연결 끊김은 지수 백오프(1초 → 30초)를 사용하고, 10초마다 ping/pong 상태 확인을 수행합니다. 3회의 pong을 놓친 클라이언트는 퇴출됩니다.

  • 세션당 120회/분의 속도 제한은 실행 중인 에이전트 루프로부터 데몬을 보호합니다.

  • 도구별 타임아웃(대부분의 작업 5–15초, 탐색 60초)은 각 도구 정의와 함께 배치되어 레지스트리에서 벗어나지 않습니다.

  • 멱등성 읽기 도구(snapshot, screenshot, text, find)는 타임아웃 시 재시도됩니다. 부작용 도구(click, type, navigate, evaluate) — 그리고 clear:true로 변경하는 console/network — 는 절대 재시도되지 않으므로 클릭이 두 번 발생할 수 없습니다.

  • 다른 프로세스가 이미 포트 7225를 점유하고 있으면 데몬은 자신이 생성하지 않은 프로세스를 종료하는 대신 시작을 거부합니다 — 충돌을 보고하므로 의도적으로 해결할 수 있습니다.

클라이언트별로 WS_PORT를 설정하여 서로 다른 포트에서 두 개의 데몬을 실행합니다:

{
  "mcpServers": {
    "browser-work": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"]
    },
    "browser-personal": {
      "command": "node",
      "args": ["/path/to/browser-controller/mcp-server/dist/index.js"],
      "env": { "WS_PORT": "9333" }
    }
  }
}

각 확장 프로그램 팝업의 포트를 일치하도록 업데이트합니다.


아키텍처

모든 것이 사용자 머신에 유지됩니다. 확장 프로그램은 localhost의 인증된 WebSocket을 통해 데몬에 연결하고, MCP 클라이언트는 로컬 IPC 소켓을 통해 데몬에 연결합니다. 클라우드도, 프록시도 없으며, 브라우저 밖으로 나가는 것은 없습니다.

browser-controller/
├── mcp-server/          MCP server (TypeScript)
│   └── src/
│       ├── daemon.ts        Single multi-client daemon (owns WS :7225)
│       ├── daemon-config.ts IPC protocol, paths, auth/enrollment tokens
│       ├── index.ts         Thin stdio MCP client (spawns daemon, multiplexes)
│       ├── bridge.ts        Extension WS server + cross-platform port probe
│       ├── register-tools.ts Progressive-disclosure wiring
│       └── tools/           One file per tool (22), registry pattern
├── extension/           Chrome extension (Manifest V3, plain JS, ES modules)
│   ├── background.js        Wiring only (~30 lines): inject router, register events, connect
│   ├── lib/                 state (buffers/locks/persistence), connection (WS lifecycle),
│   │                        router (dispatch + mutex/locks + control shield), page-exec,
│   │                        overlay, lock-ops, tab-concurrency (pure, unit-tested)
│   ├── handlers/            Tool implementations: navigation, interaction, inspection, tabs, cdp
│   ├── utils/               navigation + smart-selector fallback resolution
│   ├── events.js            chrome.* listeners (console capture, popup, webRequest, lifecycle)
│   ├── content.js           Console capture
│   └── popup/               Fixed tabbed shell (Tabs · Agents · Settings) + collapsible activity bar
├── agent-config/        Pre-built configs for Cursor + Claude Code
│   ├── cursor/              Rules and commands
│   ├── skills/              Browser automation skill
│   └── setup.mjs            One-command installer
└── tests/               15 suites / 215 tests

스택: TypeScript (strict) · MCP SDK · WebSocket · Chrome Extension Manifest V3 · Vitest

개발

git clone https://github.com/compnew2006/browser-controller.git
cd browser-controller
npm install
npm run build
npm test

명령어

기능

npm run build

TypeScript 컴파일 → mcp-server/dist/

npm run dev

감시 모드

npm test

전체 테스트 스위트 실행(215개 테스트)

npm run typecheck

출력 없이 타입 검사

npm run setup:cursor

Cursor 규칙 + 명령 설치

npm run setup:claude

Claude Code AGENTS.md 설치

테스트 스위트는 WebSocket 브리지(토큰 인증 거부 및 통합 오류 채널 포함), 도구 레지스트리, 데몬 수명 주기(하트비트 퇴출, 속도 제한, IPC 인증), 탭별 동시성(같은 탭 직렬화 + 탭 간 병렬 처리), 그리고 모의 chrome API를 통한 확장 프로그램 동작(라우터 디스패치, 실드 의미론, evaluate 왕복, iframe 관통, 대화상자 구조)을 다룹니다. CI는 Node 20 및 22에서 스위트를 실행하며 CodeQL 및 Scorecard 스캔도 수행합니다.

기존 설치 업데이트

git pull
npm install
npm run build

그런 다음 두 가지 수동 단계가 필요합니다: chrome://extensions에서 확장 프로그램을 다시 로드하고(실행 중인 서비스 워커는 파일 변경을 자체적으로 감지하지 않음), 데몬을 다시 시작합니다 — 데몬은 장기 실행 프로세스이므로 dist/도 다시 로드하지 않습니다(종료하거나 MCP 클라이언트를 다시 시작하면 다음 실행 시 새 빌드로 다시 생성됩니다).


FAQ

그것이 바로 핵심입니다. 확장 프로그램은 실제 Chrome 내부에서 실행됩니다 — 동일한 쿠키, 동일한 세션, 동일한 로컬 저장소. 재인증이 필요 없습니다.

아니요. MCP 클라이언트, 데몬, 확장 프로그램은 모두 localhost(IPC 소켓 + WebSocket)를 통해 통신합니다. 머신 밖으로 나가는 것은 없습니다. 분석, 원격 측정, 클라우드 구성 요소가 없습니다. 위협 모델, 인증 설계, 최초 접촉 TOFU 창에 대해서는 SECURITY.md를 참조하세요.

MCP 호환 클라이언트라면 무엇이든 가능합니다. Cursor, Claude Desktop, Claude Code, Windsurf, Cline 등 MCP 프로토콜을 지원하는 모든 도구가 해당됩니다. 여러 클라이언트가 동시에 동일한 데몬에 연결되어 실행될 수 있습니다.

네. 각 에이전트는 공유 데몬에 연결되어 고유한 sessionId를 받고 특정 tabId를 대상으로 합니다. 동일한 탭에 대한 작업은 탭별 뮤텍스를 통해 직렬화되고, 서로 다른 탭에 대한 작업은 병렬로 실행됩니다. 선택적으로 에이전트가 탭을 lock하여 독점 액세스를 요청할 수 있으며, 다른 에이전트는 실패하는 대신 잠금 뒤에서 대기합니다.

그럴 수 없습니다 — 조용히 넘어가지 않습니다. 모든 페이지 상호작용 도구는 tabId를 요구하며, 누락된 경우 명확한 tabId is required 오류가 표시됩니다. 에이전트는 사용자가 보고 있는 탭에서 실수로 작업할 수 없습니다. (유일한 예외는 tabId 없이 호출하는 browser_navigate로, 활성 탭을 사용합니다 — 하지만 멀티 에이전트 사용 시에는 항상 tabId를 전달해야 합니다.)

이것들이 없으면 사용자 머신의 모든 로컬 프로세스가 포트 7225에 WebSocket을 열고 인증된 브라우저 세션(은행, 이메일, 회사 SSO)을 제어할 수 있습니다. 등록 비밀 키는 확장 프로그램과 데몬을 정확히 한 번만 페어링하며(WebSocket이 존재하기 전에 대역 외로 수행), 이후 인증 토큰이 모든 연결을 인증합니다. 둘 다 ~/.browser-controller/에 모드 0600으로 저장됩니다.

그들은 처음부터 새 브라우저 인스턴스를 시작합니다 — 상태, 쿠키, 세션이 없습니다. 매번 전체 로그인 흐름을 다시 수행해야 합니다. 이 도구는 이미 열려 있고 모든 것이 로드된 브라우저에 연결합니다.


기여

버그 리포트, 기능 요청, PR은 이슈 트래커에서 환영합니다. 큰 변경 사항은 먼저 이슈를 열어주세요.

보안

SECURITY.md를 참조하세요 — localhost 전용 아키텍처, 토큰 + 등록 설계, 위협 모델, 신고 지침이 포함되어 있습니다.

라이선스

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

No tool schema history has been recorded yet.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables CLI coding agents to interact with your live browser tabs via MCP, using your real sessions and cookies without a sandbox.
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Connects AI agents to your Chrome browser via MCP, enabling real-time control of existing tabs, sessions, and application state for development workflows.
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI to control a real browser through MCP tools for clicking, typing, navigation, screenshots, and more. It supports a follow mode that tracks the active tab, plus fixed mode for controlling specific tabs.
    18
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/compnew2006/browser-controller'

If you have feedback or need assistance with the MCP directory API, please join our Discord server