BrowserMCP/mcp

Browser MCP is a Model Context Provider (MCP) server that allows AI applications to control your browser

개요

Browser MCP는 AI 코딩 어시스턴트(Claude Code, Cursor, VS Code, Codex, Claude Desktop 등)가 사용자 자신의 Chrome 브라우저를 제어할 수 있게 해주는 브리지입니다. 기존 로그인, 쿠키, 프로필을 사용하여 별도의 탭에서 작동합니다. 모든 것은 사용자 머신에서 로컬로 실행되며, 클라우드 서비스로 전송되는 것은 없습니다.

두 부분으로 구성됩니다:

Chrome 확장 프로그램(Chrome 웹 스토어에서 제공되거나 소스에서 빌드 가능)은 브라우저의 리모컨 역할을 합니다.
MCP 서버(작은 Node.js 프로그램)는 AI 앱이 시작하고 통신합니다. MCP(Model Context Protocol)는 AI 앱이 외부 도구를 호출하는 표준 방법입니다. 여기서 도구는 "브라우저"입니다.

작동 방식

AI 앱은 npx @browsermcp/mcp@latest로 MCP 서버를 시작합니다. 이 서버는 사용자 계정에 대한 데몬(백그라운드 프로세스)을 생성합니다.
AI 앱은 browser 도구 호출을 서버로 보내고, 서버는 이를 데몬으로 전달합니다.
데몬은 Playwright(브라우저 자동화 라이브러리)를 사용하여 Chrome의 탭을 제어하지만, Chrome과 직접 통신하지 않고 확장 프로그램을 통해 통신합니다.
확장 프로그램은 Chrome의 chrome.debugger API를 사용하여 실제로 브라우저를 제어하는 얇은 릴레이입니다. 127.0.0.1(사용자 자신의 머신)의 데몬에서 오는 연결만 수락합니다.

보안 모델

확장 프로그램은 의도적으로 제한적입니다:

페어링: 컴퓨터에서 처음 사용할 때 확장 프로그램의 팝업에 6자리 코드가 표시됩니다. AI 앱이 표시하는 코드와 일치하는지 확인한 후에만 허용을 클릭해야 합니다. 이렇게 하면 임의의 로컬 프로세스가 브라우저를 가로채는 것을 방지할 수 있습니다.
하드 규칙: 데몬이 요청하더라도 확장 프로그램은 시크릿 창, 브라우저 내부 페이지(예: chrome://) 또는 확장 프로그램 페이지를 여는 것을 거부합니다. 또한 팝업에서 중지를 누르면 모든 제어를 중지합니다.
로컬 전용: 확장 프로그램은 127.0.0.1의 데몬과만 통신합니다. 인터넷 트래픽이 없습니다.

구성 요소(리포지토리 레이아웃)

폴더	패키지	용도
`packages/mcp`	`@browsermcp/mcp`	MCP 서버 및 데몬
`packages/protocol`	`@browsermcp/protocol`	확장 프로그램과 데몬 간의 통신 프로토콜(페어링 포함)
`packages/extension-core`	`@browsermcp/extension-core`	확장 프로그램의 브라우저 제어 로직: 연결, 페어링, 디버거 릴레이, 탭 규칙, 배지
`apps/extension`	`@browsermcp/extension`	이 리포지토리에서 빌드된 실제 Chrome 확장 프로그램(팝업 UI 포함)

소스에서 빌드

요구 사항: Node.js 24+, pnpm(corepack enable로 활성화), Chrome 또는 Chromium 기반 브라우저(Edge, Brave, Arc 등). Firefox는 debugger API가 없어 지원되지 않습니다.

git clone https://github.com/BrowserMCP/mcp.git browsermcp
cd browsermcp
pnpm install
pnpm build

그런 다음 chrome://extensions(개발자 모드 → 압축 해제된 확장 프로그램 로드)를 통해 apps/extension/.output/chrome-mv3에서 압축 해제된 확장 프로그램을 로드합니다. 자체 빌드된 확장 프로그램은 웹 스토어 버전과 동일한 ID를 가지므로 둘을 동시에 실행할 수 없습니다. 스토어 버전이 있으면 비활성화하세요.

npm 버전 대신 빌드한 서버를 사용하려면 AI 앱의 MCP 구성을 로컬 파일로 지정하세요:

{
  "mcpServers": {
    "browsermcp": {
      "command": "node",
      "args": ["/path/to/browsermcp/packages/mcp/dist/index.js"]
    }
  }
}

참고: npx @browsermcp/mcp@latest는 자체 빌드된 확장 프로그램에서도 작동합니다. 동일한 서버이며, 이 리포지토리에서 게시된 것입니다.

업데이트

git pull
pnpm install
pnpm build

그런 다음 chrome://extensions에서 확장 프로그램을 다시 로드하고, AI 앱이 이 폴더에서 서버를 실행하는 경우 다시 시작하세요. 확장 프로그램과 서버는 한쪽이 다른 쪽보다 너무 오래된 경우 경고합니다.

개발

pnpm lint, pnpm format / pnpm format:fix — 코드 스타일(Oxlint, Oxfmt)
pnpm typecheck, pnpm test — TypeScript 검사 및 단위 테스트(Vitest). 서버 테스트에는 Playwright의 Chromium이 필요합니다: pnpm --filter @browsermcp/mcp exec playwright-core install chromium
pnpm smoke — 개발 모드로 모든 것을 빌드하고, 헤드리스 Chromium에서 확장 프로그램을 로드하고, AI 앱처럼 서버를 통해 구동합니다. 임의의 포트와 임시 BROWSER_MCP_HOME을 사용하므로 실제 Browser MCP 설정에는 영향을 미치지 않습니다. 스크린샷은 apps/extension/.output/smoke/에 저장됩니다
pnpm --filter @browsermcp/extension build:dev — apps/extension/.output/chrome-mv3-dev의 개발 빌드

라이선스 및 상표

Apache-2.0. "Browser MCP"라는 이름과 로고는 상표입니다. 수정된 버전을 게시하는 경우 이름을 변경하고 아이콘을 변경해야 합니다(TRADEMARKS.md 참조).