Blueprint MCP Server
공식Chrome 및 Firefox를 위한 MCP 기반 브라우저 자동화
문서
Blueprint MCP
모델 컨텍스트 프로토콜을 통해 AI로 실제 브라우저를 제어하세요
이것은 무엇인가요?
AI 어시스턴트가 브라우저 확장 프로그램을 통해 실제 브라우저(Chrome, Firefox, Opera)를 제어할 수 있게 해주는 MCP(모델 컨텍스트 프로토콜) 서버입니다. 헤드리스 자동화 도구와 달리, 로그인된 세션, 쿠키, 확장 프로그램이 모두 유지된 실제 브라우저 프로필을 사용합니다.
적합한 대상: 이미 로그인된 사이트와 상호작용해야 하거나 봇 탐지를 피해야 하는 AI 에이전트.
Playwright/Puppeteer 대신 이것을 사용해야 하는 이유는 무엇인가요?
| Blueprint MCP | Playwright/Puppeteer |
|---|---|
| ✅ 실제 브라우저 (헤드리스 아님) | ❌ 헤드리스 또는 새 브라우저 인스턴스 |
| ✅ 모든 사이트에 로그인 상태 유지 | ❌ 세션마다 재인증 필요 |
| ✅ 봇 탐지 회피 (실제 핑거프린트 사용) | ⚠️ 자동화된 브라우저로 탐지되는 경우 많음 |
| ✅ 기존 브라우저 확장 프로그램과 함께 작동 | ❌ 확장 프로그램 지원 안 함 |
| ✅ 설정 불필요 - 바로 사용 가능 | ⚠️ 브라우저 설치 필요 |
| ✅ Chrome, Firefox, Edge, Opera 지원 | ✅ Chrome, Firefox, Safari 지원 |
설치
1. MCP 서버 설치
npm install -g @railsblueprint/blueprint-mcp
2. 브라우저 확장 프로그램 설치
사용 중인 브라우저를 선택하세요:
Chrome / Edge / Opera
- Chrome 웹 스토어 (모든 Chromium 기반 브라우저에서 작동)
- 수동 설치: Releases에서 다운로드 후
chrome://extensions/(Chrome),edge://extensions/(Edge), 또는opera://extensions/(Opera)에서 압축 해제된 항목 로드
Firefox
- Firefox 부가 기능
- 수동 설치: Releases에서 다운로드 후
about:debugging#/runtime/this-firefox에서 로드
3. MCP 클라이언트 구성
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["@railsblueprint/blueprint-mcp@latest"]
}
}
}
Claude Code (AI 기반 CLI):
claude mcp add browser npx @railsblueprint/blueprint-mcp@latest
VS Code / Cursor (.vscode/settings.json):
{
"mcp.servers": {
"browser": {
"command": "npx",
"args": ["@railsblueprint/blueprint-mcp@latest"]
}
}
}
빠른 시작
- MCP 클라이언트 시작 (Claude Desktop, Cursor 등)
- 브라우저에서 Blueprint MCP 확장 프로그램 아이콘 클릭
- 확장 프로그램이 MCP 서버에 자동 연결됩니다
- AI 어시스턴트에게 브라우징을 요청하세요!
대화 예시:
You: "Go to GitHub and check my notifications"
AI: *navigates to github.com, clicks notifications, reads content*
You: "Fill out this form with my info"
AI: *reads form fields, fills them in, submits*
You: "Take a screenshot of this page"
AI: *captures screenshot and shows you*
작동 방식
┌─────────────────────────┐
│ AI Assistant │
│ (Claude, GPT, etc) │
└───────────┬─────────────┘
│
│ MCP Protocol
↓
┌─────────────────────────┐
│ MCP Client │
│ (Claude Desktop, etc) │
└───────────┬─────────────┘
│
│ stdio/JSON-RPC
↓
┌─────────────────────────┐
│ blueprint-mcp │
│ (this package) │
└───────────┬─────────────┘
│
│ WebSocket (localhost:5555 or cloud relay)
↓
┌─────────────────────────┐
│ Browser Extension │
└───────────┬─────────────┘
│
│ Browser Extension APIs
↓
┌─────────────────────────┐
│ Your Browser │
│ (real profile) │
└─────────────────────────┘
Free vs PRO
Free 등급 (기본)
- ✅ 로컬 WebSocket 연결 (포트 5555)
- ✅ 단일 브라우저 인스턴스
- ✅ 모든 브라우저 자동화 기능
- ✅ 계정 불필요
- ❌ 동일한 머신으로 제한
PRO 등급
- ✅ 클라우드 릴레이 - 어디서나 연결 가능
- ✅ 다중 브라우저 - 여러 브라우저 인스턴스 제어
- ✅ 공유 액세스 - 여러 AI 클라이언트가 동일한 브라우저 사용 가능
- ✅ 자동 재연결 - 네트워크 변경 시에도 연결 유지
- ✅ 우선 지원
사용 가능한 도구
MCP 서버는 AI 어시스턴트에게 다음 도구들을 제공합니다:
연결 관리
enable- 브라우저 자동화 활성화 (필수 첫 단계)disable- 브라우저 자동화 비활성화status- 연결 상태 확인auth- PRO 계정 로그인 (클라우드 릴레이 기능용)
탭 관리
browser_tabs- 브라우저 탭 나열, 생성, 연결, 닫기
탐색
browser_navigate- URL로 이동browser_navigate_back- 기록에서 뒤로 가기
콘텐츠 및 검사
browser_snapshot- 접근 가능한 페이지 콘텐츠 가져오기 (페이지 읽기에 권장)browser_take_screenshot- 시각적 스크린샷 캡처browser_console_messages- 브라우저 콘솔 로그 가져오기browser_network_requests- 여러 작업을 지원하는 강력한 네트워크 모니터링 및 재생 도구:- 목록 모드 (기본값): 필터링 및 페이지네이션이 포함된 경량 개요 (기본값: 요청 20개)
- 필터:
urlPattern(부분 문자열),method(GET/POST),status(200/404),resourceType(xhr/fetch/script) - 페이지네이션:
limit(기본값: 20),offset(기본값: 0) - 예시:
action='list', urlPattern='api/users', method='GET', limit=10
- 필터:
- 세부 정보 모드: 헤더와 본문을 포함한 특정 요청의 전체 요청/응답 데이터
- JSONPath 필터링: JSONPath 구문을 사용하여 대용량 JSON 응답 쿼리 (예:
$.data.items[0]) - 재생 모드: 원본 헤더와 인증 정보로 캡처된 요청 재실행
- 지우기 모드: 메모리 확보를 위해 캡처된 기록 지우기
- 예시:
action='details', requestId='12345.67', jsonPath='$.data.users[0]'
- 목록 모드 (기본값): 필터링 및 페이지네이션이 포함된 경량 개요 (기본값: 요청 20개)
browser_extract_content- 페이지 콘텐츠를 마크다운으로 추출
상호작용
browser_interact- 여러 작업을 순서대로 수행 (클릭, 입력, 호버, 대기 등)browser_click- 요소 클릭browser_type- 입력란에 텍스트 입력browser_hover- 요소 위에 마우스 호버browser_select_option- 드롭다운 옵션 선택browser_fill_form- 여러 양식 필드를 한 번에 채우기browser_press_key- 키보드 키 누르기browser_drag- 요소 드래그 앤 드롭
고급
browser_evaluate- 페이지 컨텍스트에서 JavaScript 실행browser_handle_dialog- alert/confirm/prompt 대화상자 처리browser_file_upload- 파일 입력을 통한 파일 업로드browser_window- 브라우저 창 크기 조정, 최소화, 최대화browser_pdf_save- 현재 페이지를 PDF로 저장browser_performance_metrics- 성능 지표 가져오기browser_verify_text_visible- 텍스트 존재 확인 (테스트용)browser_verify_element_visible- 요소 존재 확인 (테스트용)
확장 프로그램 관리
browser_list_extensions- 설치된 브라우저 확장 프로그램 나열browser_reload_extensions- 압축 해제된 확장 프로그램 다시 로드 (개발 중에 유용)
개발
사전 요구 사항
- Node.js 18 이상
- 지원되는 브라우저 (Chrome, Firefox, Edge, 또는 Opera)
- npm 또는 yarn
설정
# Clone the repository
git clone https://github.com/railsblueprint/blueprint-mcp.git
cd blueprint-mcp
# Install server dependencies
cd server
npm install
cd ..
# Install Chrome extension dependencies
cd extensions/chrome
npm install
cd ../..
개발 환경에서 실행
터미널 1: 디버그 모드로 MCP 서버 시작
cd server
node cli.js --debug
터미널 2: Chrome 확장 프로그램 빌드
cd extensions/chrome
npm run build
# or for watch mode:
npm run dev
참고: Firefox 확장 프로그램은 빌드 단계가 필요하지 않습니다. 순수 JavaScript를 사용하며 extensions/firefox/에서 직접 로드할 수 있습니다.
브라우저에 확장 프로그램 로드:
Chromium 기반 브라우저 (Chrome, Edge, Opera)의 경우:
chrome://extensions/(Chrome),edge://extensions/(Edge), 또는opera://extensions/(Opera) 열기- "개발자 모드" 활성화
- "압축 해제된 항목 로드" 클릭
extensions/chrome/dist폴더 선택
Firefox의 경우:
about:debugging#/runtime/this-firefox열기- "임시 부가 기능 로드" 클릭
extensions/firefox폴더에서 아무 파일이나 선택
프로젝트 구조
blueprint-mcp/
├── server/ # MCP Server
│ ├── cli.js # Server entry point
│ ├── src/
│ │ ├── statefulBackend.js # Connection state management
│ │ ├── unifiedBackend.js # MCP tool implementations
│ │ ├── extensionServer.js # WebSocket server for extension
│ │ ├── mcpConnection.js # Proxy/relay connection handling
│ │ ├── transport.js # Transport abstraction layer
│ │ ├── oauth.js # OAuth2 client for PRO features
│ │ └── fileLogger.js # Debug logging
│ └── tests/ # Server test suites
├── extensions/ # Browser Extensions
│ ├── chrome/ # Chrome extension (TypeScript + Vite)
│ │ └── src/
│ │ ├── background.ts # Extension service worker
│ │ ├── content-script.ts # Page content injection
│ │ └── utils/ # Utility functions
│ ├── firefox/ # Firefox extension (Vanilla JS)
│ │ └── src/
│ │ ├── background.js # Service worker
│ │ └── content-script.js # Page injection
│ ├── shared/ # Shared code between extensions
│ └── build-*.js # Build scripts for each browser
├── docs/ # Documentation
│ ├── testing/ # Test documentation
│ ├── architecture/ # Architecture docs
│ └── stores/ # Browser store assets
└── releases/ # Built extensions for distribution
├── chrome/
├── firefox/
├── edge/
└── opera/
테스트
# Run tests
npm test
# Run with coverage
npm run test:coverage
문서:
구성
서버는 합리적인 기본값으로 바로 작동합니다. 고급 구성을 위한 정보:
환경 변수
프로젝트 루트에 .env 파일을 생성하세요:
# Authentication server (PRO features)
AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com
# Local WebSocket port (Free tier)
MCP_PORT=5555
# Debug mode
DEBUG=false
명령줄 옵션
blueprint-mcp --debug # Enable verbose logging
blueprint-mcp --port 8080 # Use custom WebSocket port (default: 5555)
blueprint-mcp --debug --port 8080 # Combine options
참고: 포트를 변경하면 브라우저 확장 프로그램 설정도 일치하도록 업데이트해야 합니다.
문제 해결
확장 프로그램이 연결되지 않음
- 확장 프로그램이 설치되고 활성화되었는지 확인하세요
- 확장 프로그램 아이콘을 클릭하세요 - "연결됨"이 표시되어야 합니다
- MCP 서버가 실행 중인지 확인하세요 (포트 5555에서 프로세스 확인)
- 확장 프로그램을 다시 로드해 보세요
"포트 5555가 이미 사용 중입니다"
다른 인스턴스가 실행 중입니다. 다음 중 하나를 수행할 수 있습니다:
- 기존 프로세스 종료:
lsof -ti:5555 | xargs kill -9
- 다른 포트 사용:
blueprint-mcp --port 8080
브라우저 도구가 작동하지 않음
enable을 먼저 호출했는지 확인하세요browser_tabs로 탭에 연결했는지 확인하세요- 탭이 여전히 존재하는지 확인하세요 (닫히지 않았는지)
도움 받기
기여
기여를 환영합니다! 가이드라인은 CONTRIBUTING.md를 참조하세요.
보안
이 도구는 AI 어시스턴트에게 브라우저 제어 권한을 부여합니다. 다음 사항을 검토하세요:
- MCP 서버는 기본적으로 로컬 연결만 허용합니다 (localhost:5555)
- PRO 릴레이 연결은 OAuth를 통해 인증됩니다
- 확장 프로그램은 명시적인 사용자 작업을 통해 연결해야 합니다
- 모든 브라우저 작업은 브라우저의 권한 시스템을 통과합니다
보안 문제를 발견하셨나요? 공개 이슈를 제출하는 대신 [email protected]으로 이메일을 보내주세요.
크레딧
이 프로젝트는 원래 Microsoft의 Playwright MCP 구현에서 영감을 받았지만, Playwright 대신 브라우저 확장 프로그램 기반 자동화를 사용하도록 완전히 재작성되었습니다. 아키텍처, 구현 방식, 접근 방식이 근본적으로 다릅니다.
주요 차이점:
- Playwright가 아닌 DevTools 프로토콜을 사용하는 브라우저 확장 프로그램 사용
- 격리된 컨텍스트가 아닌 실제 브라우저 프로필로 작동
- CDP 릴레이가 아닌 WebSocket 기반 통신
- 원격 액세스를 위한 클라우드 릴레이 옵션
- Free 및 PRO 등급 모델
- 다중 브라우저 지원 (Chrome, Firefox, Edge, Opera)
MCP를 통한 브라우저 자동화를 개척한 Playwright 팀에 감사드립니다.
라이선스
Apache License 2.0 - LICENSE 참조
Copyright (c) 2025 Rails Blueprint
❤️로 제작: Rails Blueprint