브라우저 사용 MCP 서버

프로젝트 참고 : 이 MCP 서버 구현은 브라우저 사용/웹 UI 기반을 기반으로 합니다. 핵심 브라우저 자동화 로직과 구성 패턴은 원래 프로젝트에서 가져온 것입니다.

자연어 브라우저 제어 및 웹 조사를 위한 모델 컨텍스트 프로토콜(MCP)을 구현하는 AI 기반 브라우저 자동화 서버입니다.

특징

• 🧠 MCP 통합 - AI 에이전트 통신을 위한 전체 프로토콜 구현.

• 🌐 브라우저 자동화 - 자연어를 통한 페이지 탐색, 양식 작성, 요소 상호작용( run_browser_agent 도구).

• 👁️ 시각적 이해 - 시각을 갖춘 LLM을 위한 선택적 스크린샷 분석.

• 🔄 상태 지속성 - 여러 MCP 호출에 걸쳐 브라우저 세션을 관리하거나 사용자 브라우저에 연결하는 옵션입니다.

• 🔌 다중 LLM 지원 - OpenAI, Anthropic, Azure, DeepSeek, Google, Mistral, Ollama, OpenRouter, Alibaba, Moonshot, Unbound AI와 통합됩니다.

• 🔍 심층 조사 도구 - 여러 단계로 이루어진 웹 조사와 보고서 생성을 위한 전용 도구( run_deep_search 도구).

• ⚙️ 환경 변수 구성 - 환경 변수를 통해 완벽하게 구성 가능합니다.

• 🔗 CDP 연결 - Chrome DevTools 프로토콜을 통해 사용자가 시작한 Chrome/Chromium 인스턴스에 연결하고 제어할 수 있는 기능입니다.

빠른 시작

필수 조건

• Python 3.11 이상

• uv (빠른 Python 패키지 설치 프로그램): pip install uv

• Chrome/Chromium 브라우저 설치됨

• Playwright 브라우저 설치: uv sync 후 uv run playwright install

MCP 클라이언트(예: Claude Desktop)와의 통합

Claude Desktop과 같은 클라이언트가 이 서버에 연결되도록 구성할 수 있습니다. 클라이언트 구성에 다음 구조를 추가하세요(예: claude_desktop_config.json ). 필요에 따라 경로 및 환경 변수를 조정하세요.

지엑스피1

중요: command 과 args 서버를 실행할 방식(설치된 패키지 또는 소스 디렉터리)을 올바르게 지정해야 합니다. env 섹션에 필요한 API 키를 설정하세요.

MCP 도구

이 서버는 모델 컨텍스트 프로토콜을 통해 다음 도구를 제공합니다.

동기 도구(완료 대기)

1. run_browser_agent

   • 설명: 자연어 명령어에 따라 브라우저 자동화 작업을 실행하고 완료될 때까지 기다립니다. MCP_ 로 시작하는 설정(예: MCP_HEADLESS , MCP_MAX_STEPS )을 사용합니다.

   • 인수:

     • task (문자열, 필수): 주요 작업 또는 목표.

     • add_infos (문자열, 선택 사항): 에이전트에 대한 추가 컨텍스트 또는 힌트( custom 에이전트 유형에서 사용됨).

   • 반환값: (문자열) 에이전트가 추출한 최종 결과 또는 오류 메시지.

2. run_deep_search

   • 설명: 특정 주제에 대한 심층적인 웹 조사를 수행하고 보고서를 생성한 후 완료될 때까지 기다립니다. MCP_RESEARCH_ 가 붙은 설정과 일반적인 BROWSER_ 설정(예: BROWSER_HEADLESS )을 사용합니다.

   • 인수:

     • research_task (문자열, 필수): 연구 주제 또는 질문.

     • max_search_iterations (정수, 선택 사항, 기본값: 10): 최대 검색 주기.

     • max_query_per_iteration (정수, 선택 사항, 기본값: 3): 사이클당 최대 검색 쿼리.

   • 반환값: (문자열) 파일 경로 또는 오류 메시지를 포함한 Markdown 형식의 생성된 연구 보고서입니다.

구성(환경 변수)

환경 변수를 사용하여 서버를 구성하세요. 환경 변수는 시스템에 설정하거나 프로젝트 루트의 .env 파일에 저장할 수 있습니다.

지원되는 LLM 공급자(

openai , azure_openai , anthropic , google , mistral , ollama , deepseek , openrouter , alibaba , moonshot , unbound

자신의 브라우저에 연결하기(CDP)

서버가 자체 브라우저 인스턴스를 실행하고 관리하는 대신, 사용자가 직접 실행하고 관리하는 Chrome/Chromium 브라우저에 서버를 연결할 수 있습니다. 이 기능은 다음과 같은 경우에 유용합니다.

• 기존 브라우저 프로필(쿠키, 로그인, 확장 프로그램)을 사용합니다.

• 브라우저 창에서 직접 자동화를 관찰합니다.

• 복잡한 시나리오 디버깅.

단계:

1. 원격 디버깅을 활성화하여 Chrome/Chromium을 실행하세요. 터미널이나 명령 프롬프트를 열고 운영 체제에 맞는 명령어를 실행하세요. 이렇게 하면 Chrome이 특정 포트(예: 9222)에서 연결을 수신 대기하도록 설정됩니다.

   • 맥OS:

     /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

     (크롬이 다른 곳에 설치되어 있는 경우 경로를 조정하세요)

   • 리눅스:

     google-chrome --remote-debugging-port=9222 # or chromium-browser --remote-debugging-port=9222

   • Windows(명령 프롬프트):

     "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

     (필요한 경우 Chrome 설치 경로를 조정하세요)

   • 윈도우(PowerShell):

     & "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

     (필요한 경우 Chrome 설치 경로를 조정하세요)

   참고: 포트 9222가 이미 사용 중인 경우 다른 포트(예: 9223)를 선택하고 CHROME_CDP 환경 변수에 동일한 포트를 사용하세요.

2. 환경 변수 구성: MCP 서버를 시작하기 전에 .env 파일이나 시스템 환경에서 다음 환경 변수를 설정하세요.

   MCP_USE_OWN_BROWSER=true CHROME_CDP=http://localhost:9222 # Use the same port you launched Chrome with

   • MCP_USE_OWN_BROWSER=true : 서버에 브라우저를 새로 시작하는 대신 기존 브라우저에 연결하도록 지시합니다.

   • CHROME_CDP : 서버가 브라우저의 DevTools 프로토콜 엔드포인트에 연결할 수 있는 URL을 지정합니다.

3. MCP 서버 실행: 평소와 같이 서버를 시작합니다.

   uv run mcp-server-browser-use

이제 run_browser_agent 또는 run_deep_search 도구를 사용하면 서버가 새 인스턴스를 만드는 대신 실행 중인 Chrome 인스턴스에 연결됩니다.

중요 고려 사항:

• --remote-debugging-port 로 실행된 브라우저는 MCP 서버가 실행되는 동안 열려 있어야 하며, 서버와 상호 작용해야 합니다.

• MCP 서버가 실행 중인 위치에서 CHROME_CDP URL에 접근할 수 있는지 확인하세요(일반적으로 동일한 컴퓨터에서 실행 중인 경우 http://localhost:PORT ).

• 자체 브라우저를 사용하면 서버가 해당 브라우저의 상태(열린 탭, 로그인된 세션)를 상속받습니다. 자동화 작업 시 이 점에 유의하세요.

• MCP_USE_OWN_BROWSER=true 이면 MCP_HEADLESS , BROWSER_HEADLESS , MCP_KEEP_BROWSER_OPEN 과 같은 설정은 무시됩니다. 창 크기는 브라우저 창에 따라 결정됩니다.

개발

문제 해결

• 브라우저 충돌 : CHROME_CDP ( MCP_USE_OWN_BROWSER=false )를 사용 하지 않는 경우 CHROME_USER_DATA 지정된 경우 다른 충돌하는 Chrome 인스턴스가 동일한 사용자 데이터 디렉토리에서 실행되지 않는지 확인합니다.

• CDP 연결 문제 : MCP_USE_OWN_BROWSER=true 사용하는 경우:

  • Chrome이 --remote-debugging-port 플래그로 실행되었는지 확인하세요.

  • CHROME_CDP 의 포트가 Chrome을 실행할 때 사용한 포트와 일치하는지 확인하세요.

  • 지정된 포트로의 연결을 차단하는 방화벽 문제가 있는지 확인하세요.

  • 브라우저가 계속 실행 중인지 확인하세요.

• API 오류 : 선택한 MCP_MODEL_PROVIDER 에 올바른 API 키 환경 변수( OPENAI_API_KEY , ANTHROPIC_API_KEY 등)가 설정되어 있는지 또는 MCP_API_KEY 가 설정되어 있는지 다시 한번 확인하세요. 키와 엔드포인트를 확인하세요(Azure의 경우 AZURE_OPENAI_ENDPOINT 가 필요합니다).

• 시각 문제 : 시각 기능을 사용하는 경우 MCP_USE_VISION=true 설정하고 선택한 LLM 모델이 시각을 지원하는지 확인하세요.

• 종속성 문제 : uv sync 실행하여 모든 종속성이 올바르게 설치되었는지 확인하세요. pyproject.toml 확인하세요.

• 로깅 : 자세한 오류 메시지는 LOG_FILE (기본값: mcp_server_browser_use.log )로 지정된 로그 파일을 확인하세요. 더 자세한 출력을 원하면 BROWSER_USE_LOGGING_LEVEL 값을 DEBUG 로 높이세요.

특허

MIT - 자세한 내용은 라이센스를 참조하세요.