브라우저 사용 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 도구

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

동기 도구(완료 대기)

run_browser_agent
- 설명: 자연어 명령어에 따라 브라우저 자동화 작업을 실행하고 완료될 때까지 기다립니다. MCP_ 로 시작하는 설정(예: MCP_HEADLESS , MCP_MAX_STEPS )을 사용합니다.
- 인수:
  - task (문자열, 필수): 주요 작업 또는 목표.
  - add_infos (문자열, 선택 사항): 에이전트에 대한 추가 컨텍스트 또는 힌트( custom 에이전트 유형에서 사용됨).
- 반환값: (문자열) 에이전트가 추출한 최종 결과 또는 오류 메시지.
run_deep_search
- 설명: 특정 주제에 대한 심층적인 웹 조사를 수행하고 보고서를 생성한 후 완료될 때까지 기다립니다. MCP_RESEARCH_ 가 붙은 설정과 일반적인 BROWSER_ 설정(예: BROWSER_HEADLESS )을 사용합니다.
- 인수:
  - research_task (문자열, 필수): 연구 주제 또는 질문.
  - max_search_iterations (정수, 선택 사항, 기본값: 10): 최대 검색 주기.
  - max_query_per_iteration (정수, 선택 사항, 기본값: 3): 사이클당 최대 검색 쿼리.
- 반환값: (문자열) 파일 경로 또는 오류 메시지를 포함한 Markdown 형식의 생성된 연구 보고서입니다.

구성(환경 변수)

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

변하기 쉬운	설명	필수의?	기본값	예시 값
LLM 설정
`MCP_MODEL_PROVIDER`	사용할 LLM 제공 기관입니다. 아래 옵션을 참조하세요.	예	`anthropic`	`openrouter`
`MCP_MODEL_NAME`	선택한 공급업체의 특정 모델 이름입니다.	아니요	`claude-3-7-sonnet-20250219`	`anthropic/claude-3.7-sonnet`
`MCP_TEMPERATURE`	LLM 온도(0.0-2.0). 무작위성을 제어합니다.	아니요	`0.0`	`0.7`
`MCP_TOOL_CALLING_METHOD`	도구 호출 메서드('auto', 'json_schema', 'function_calling'). `run_browser_agent` 에 영향을 미칩니다.	아니요	`auto`	`json_schema`
`MCP_MAX_INPUT_TOKENS`	`run_browser_agent` 에 대한 LLM 컨텍스트의 최대 입력 토큰입니다.	아니요	`128000`	`64000`
`MCP_BASE_URL`	선택 사항: LLM 공급자의 기본 URL에 대한 일반적인 재정의입니다.	아니요	공급자별	`http://localhost:8080/v1`
`MCP_API_KEY`	선택 사항: LLM 공급자의 API 키에 대한 일반적인 재정의(공급자별 키보다 우선함).	아니요	-	`sk-...`
공급자 API 키	`MCP_API_KEY` 설정되지 않은 경우 `MCP_MODEL_PROVIDER` 에 따라 필요합니다.
`OPENAI_API_KEY`	OpenAI의 API 키.	사용하는 경우	-	`sk-...`
`ANTHROPIC_API_KEY`	Anthropic의 API 키.	사용하는 경우	-	`sk-ant-...`
`GOOGLE_API_KEY`	Google AI(Gemini)의 API 키.	사용하는 경우	-	`AIza...`
`AZURE_OPENAI_API_KEY`	Azure OpenAI의 API 키.	사용하는 경우	-	`...`
`DEEPSEEK_API_KEY`	DeepSeek의 API 키.	사용하는 경우	-	`sk-...`
`MISTRAL_API_KEY`	Mistral AI의 API 키.	사용하는 경우	-	`...`
`OPENROUTER_API_KEY`	OpenRouter의 API 키.	사용하는 경우	-	`sk-or-...`
`ALIBABA_API_KEY`	Alibaba Cloud(DashScope)의 API 키.	사용하는 경우	-	`sk-...`
`MOONSHOT_API_KEY`	Moonshot AI의 API 키.	사용하는 경우	-	`sk-...`
`UNBOUND_API_KEY`	Unbound AI의 API 키.	사용하는 경우	-	`...`
공급자 엔드포인트	선택 사항: 기본 API 엔드포인트를 재정의합니다.
`OPENAI_ENDPOINT`	OpenAI API 엔드포인트 URL.	아니요	`https://api.openai.com/v1`
`ANTHROPIC_ENDPOINT`	Anthropic API 엔드포인트 URL입니다.	아니요	`https://api.anthropic.com`
`AZURE_OPENAI_ENDPOINT`	Azure를 사용하는 경우 필수입니다. Azure 리소스 엔드포인트입니다.	사용하는 경우	-	`https://res.openai.azure.com/`
`AZURE_OPENAI_API_VERSION`	Azure API 버전.	아니요	`2025-01-01-preview`	`2023-12-01-preview`
`DEEPSEEK_ENDPOINT`	DeepSeek API 엔드포인트 URL.	아니요	`https://api.deepseek.com`
`MISTRAL_ENDPOINT`	미스트랄 API 엔드포인트 URL.	아니요	`https://api.mistral.ai/v1`
`OLLAMA_ENDPOINT`	Ollama API 엔드포인트 URL.	아니요	`http://localhost:11434`	`http://ollama.local:11434`
`OPENROUTER_ENDPOINT`	OpenRouter API 엔드포인트 URL.	아니요	`https://openrouter.ai/api/v1`
`ALIBABA_ENDPOINT`	Alibaba(DashScope) API 엔드포인트 URL.	아니요	`https://dashscope...v1`
`MOONSHOT_ENDPOINT`	Moonshot API 엔드포인트 URL.	아니요	`https://api.moonshot.cn/v1`
`UNBOUND_ENDPOINT`	바인딩되지 않은 AI API 엔드포인트 URL입니다.	아니요	`https://api.getunbound.ai`
올라마 특정
`OLLAMA_NUM_CTX`	Ollama 모델의 컨텍스트 창 크기.	아니요	`32000`	`8192`
`OLLAMA_NUM_PREDICT`	Ollama 모델을 예측할 수 있는 최대 토큰입니다.	아니요	`1024`	`2048`
에이전트 설정( `run_browser_agent` )
`MCP_AGENT_TYPE`	`run_browser_agent` ('org' 또는 'custom')에 대한 에이전트 구현.	아니요	`org`	`custom`
`MCP_MAX_STEPS`	에이전트당 실행 가능한 최대 단계 수입니다.	아니요	`100`	`50`
`MCP_USE_VISION`	비전 기능(스크린샷 분석)을 활성화합니다.	아니요	`true`	`false`
`MCP_MAX_ACTIONS_PER_STEP`	에이전트 단계당 최대 작업 수.	아니요	`5`	`10`
`MCP_KEEP_BROWSER_OPEN`	`run_browser_agent` 호출 사이에 브라우저를 서버에서 관리하도록 유지합니다( `MCP_USE_OWN_BROWSER=false` 인 경우).	아니요	`false`	`true`
`MCP_ENABLE_RECORDING`	`run_browser_agent` 에 대해 Playwright 비디오 녹화를 활성화합니다.	아니요	`false`	`true`
`MCP_SAVE_RECORDING_PATH`	에이전트 실행 비디오 녹화를 저장하는 경로( `MCP_ENABLE_RECORDING=true` 인 경우 필수).	녹음하는 경우	-	`./tmp/recordings`
`MCP_AGENT_HISTORY_PATH`	에이전트 내역 JSON 파일을 저장하는 디렉토리입니다.	아니요	`./tmp/agent_history`	`./agent_runs`
`MCP_HEADLESS`	`run_browser_agent` 도구를 위해 특별히 UI 없이 브라우저를 실행합니다.	아니요	`true`	`false`
`MCP_DISABLE_SECURITY`	`run_browser_agent` 도구에 대해 브라우저 보안 기능을 비활성화합니다(신중하게 사용하세요).	아니요	`true`	`false`
심층 연구 설정( `run_deep_search` )
`MCP_RESEARCH_MAX_ITERATIONS`	심층 연구를 위한 최대 검색 반복 횟수.	아니요	`10`	`5`
`MCP_RESEARCH_MAX_QUERY`	반복당 최대 검색 쿼리.	아니요	`3`	`5`
`MCP_RESEARCH_USE_OWN_BROWSER`	조사를 위해 별도의 브라우저 인스턴스를 사용합니다( `MCP_USE_OWN_BROWSER=true` 인 경우 `CHROME_CDP` 가 필요합니다).	아니요	`false`	`true`
`MCP_RESEARCH_SAVE_DIR`	연구 결과물(보고서, 결과)을 저장하는 디렉토리입니다.	아니요	`./tmp/deep_research/{task_id}`	`./research_output`
`MCP_RESEARCH_AGENT_MAX_STEPS`	심층 연구 내 하위 에이전트의 최대 단계.	아니요	`10`	`15`
브라우저 설정(일반 및 특정 도구 재정의)
`MCP_USE_OWN_BROWSER`	새 브라우저를 시작하는 대신 `CHROME_CDP` 를 통해 사용자 브라우저에 연결하려면 true로 설정합니다.	아니요	`false`	`true`
`CHROME_CDP`	DevTools 프로토콜 URL을 통해 기존 Chrome에 연결합니다. `MCP_USE_OWN_BROWSER=true` 인 경우 필수입니다.	`MCP_USE_OWN_BROWSER=true` 인 경우	-	`http://localhost:9222`
`BROWSER_HEADLESS`	UI 없이 브라우저를 실행합니다. 주로 `run_deep_search` 영향을 미칩니다. `MCP_HEADLESS` 도 참조하세요.	아니요	`true`	`false`
`BROWSER_DISABLE_SECURITY`	일반 브라우저 보안 설정입니다. `MCP_DISABLE_SECURITY` 도 참조하세요.	아니요	`false`	`true`
`CHROME_PATH`	Chrome/Chromium 실행 파일의 경로입니다.	아니요	-	`/usr/bin/chromium-browser`
`CHROME_USER_DATA`	Chrome 사용자 데이터 디렉터리 경로(영구 세션의 경우 `CHROME_CDP` 와 함께 사용하면 유용함).	아니요	-	`~/.config/google-chrome/Profile 1`
`BROWSER_TRACE_PATH`	Playwright 추적 파일을 저장하는 디렉토리입니다(디버깅에 유용함).	아니요	`./tmp/trace`	`./traces`
`BROWSER_WINDOW_WIDTH`	브라우저 창 너비(픽셀).	아니요	`1280`	`1920`
`BROWSER_WINDOW_HEIGHT`	브라우저 창 높이(픽셀).	아니요	`720`	`1080`
서버 및 로깅
`LOG_FILE`	서버 로그 파일의 경로입니다.	아니요	`mcp_server_browser_use.log`	`/var/log/mcp_browser.log`
`BROWSER_USE_LOGGING_LEVEL`	로깅 수준( `DEBUG` , `INFO` , `WARNING` , `ERROR` , `CRITICAL` ).	아니요	`INFO`	`DEBUG`
`ANONYMIZED_TELEMETRY`	익명화된 원격 측정을 활성화/비활성화합니다( `true` / `false` ).	아니요	`true`	`false`

지원되는 LLM 공급자( MCP_MODEL_PROVIDER ):

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

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

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

기존 브라우저 프로필(쿠키, 로그인, 확장 프로그램)을 사용합니다.
브라우저 창에서 직접 자동화를 관찰합니다.
복잡한 시나리오 디버깅.

단계:

원격 디버깅을 활성화하여 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 환경 변수에 동일한 포트를 사용하세요.
환경 변수 구성: 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을 지정합니다.
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 과 같은 설정은 무시됩니다. 창 크기는 브라우저 창에 따라 결정됩니다.

개발

# Install dev dependencies and sync project deps
uv sync --dev

# Install playwright browsers
uv run playwright install

# Run with debugger (Example connecting to own browser via CDP)
# 1. Launch Chrome: google-chrome --remote-debugging-port=9222
# 2. Run inspector command:
npx @modelcontextprotocol/inspector@latest \
  -e OPENROUTER_API_KEY=$OPENROUTER_API_KEY \
  -e MCP_MODEL_PROVIDER=openrouter \
  -e MCP_MODEL_NAME=anthropic/claude-3.7-sonnet \
  -e MCP_USE_OWN_BROWSER=true \
  -e CHROME_CDP=http://localhost:9222 \
  uv --directory . run mcp run src/mcp_server_browser_use/server.py
# Note: Change timeout in inspector's config panel if needed (default is 10 seconds)

문제 해결

브라우저 충돌 : 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 - 자세한 내용은 라이센스를 참조하세요.

Browser-Use MCP Server

Integrations