브라우저 사용 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 인스턴스에 연결하고 제어할 수 있는 기능입니다.
Related MCP server: Browser Automation MCP Server
빠른 시작
필수 조건
Python 3.11 이상
uv(빠른 Python 패키지 설치 프로그램):pip install uvChrome/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 설정 | ||||
| 사용할 LLM 제공 기관입니다. 아래 옵션을 참조하세요. | 예 |
|
|
| 선택한 공급업체의 특정 모델 이름입니다. | 아니요 |
|
|
| LLM 온도(0.0-2.0). 무작위성을 제어합니다. | 아니요 |
|
|
| 도구 호출 메서드('auto', 'json_schema', 'function_calling').
에 영향을 미칩니다. | 아니요 |
|
|
|
에 대한 LLM 컨텍스트의 최대 입력 토큰입니다. | 아니요 |
|
|
| 선택 사항: LLM 공급자의 기본 URL에 대한 일반적인 재정의입니다. | 아니요 | 공급자별 |
|
| 선택 사항: LLM 공급자의 API 키에 대한 일반적인 재정의(공급자별 키보다 우선함). | 아니요 | - |
|
공급자 API 키 |
| |||
| OpenAI의 API 키. | 사용하는 경우 | - |
|
| Anthropic의 API 키. | 사용하는 경우 | - |
|
| Google AI(Gemini)의 API 키. | 사용하는 경우 | - |
|
| Azure OpenAI의 API 키. | 사용하는 경우 | - |
|
| DeepSeek의 API 키. | 사용하는 경우 | - |
|
| Mistral AI의 API 키. | 사용하는 경우 | - |
|
| OpenRouter의 API 키. | 사용하는 경우 | - |
|
| Alibaba Cloud(DashScope)의 API 키. | 사용하는 경우 | - |
|
| Moonshot AI의 API 키. | 사용하는 경우 | - |
|
| Unbound AI의 API 키. | 사용하는 경우 | - |
|
공급자 엔드포인트 | 선택 사항: 기본 API 엔드포인트를 재정의합니다. | |||
| OpenAI API 엔드포인트 URL. | 아니요 |
| |
| Anthropic API 엔드포인트 URL입니다. | 아니요 |
| |
| Azure를 사용하는 경우 필수입니다. Azure 리소스 엔드포인트입니다. | 사용하는 경우 | - |
|
| Azure API 버전. | 아니요 |
|
|
| DeepSeek API 엔드포인트 URL. | 아니요 |
| |
| 미스트랄 API 엔드포인트 URL. | 아니요 |
| |
| Ollama API 엔드포인트 URL. | 아니요 |
|
|
| OpenRouter API 엔드포인트 URL. | 아니요 |
| |
| Alibaba(DashScope) API 엔드포인트 URL. | 아니요 |
| |
| Moonshot API 엔드포인트 URL. | 아니요 |
| |
| 바인딩되지 않은 AI API 엔드포인트 URL입니다. | 아니요 |
| |
올라마 특정 | ||||
| Ollama 모델의 컨텍스트 창 크기. | 아니요 |
|
|
| Ollama 모델을 예측할 수 있는 최대 토큰입니다. | 아니요 |
|
|
에이전트 설정( | ||||
|
('org' 또는 'custom')에 대한 에이전트 구현. | 아니요 |
|
|
| 에이전트당 실행 가능한 최대 단계 수입니다. | 아니요 |
|
|
| 비전 기능(스크린샷 분석)을 활성화합니다. | 아니요 |
|
|
| 에이전트 단계당 최대 작업 수. | 아니요 |
|
|
|
호출 사이에 브라우저를 서버에서 관리하도록 유지합니다(
인 경우). | 아니요 |
|
|
|
에 대해 Playwright 비디오 녹화를 활성화합니다. | 아니요 |
|
|
| 에이전트 실행 비디오 녹화를 저장하는 경로(
인 경우 필수). | 녹음하는 경우 | - |
|
| 에이전트 내역 JSON 파일을 저장하는 디렉토리입니다. | 아니요 |
|
|
|
도구를 위해 특별히 UI 없이 브라우저를 실행합니다. | 아니요 |
|
|
|
도구에 대해 브라우저 보안 기능을 비활성화합니다(신중하게 사용하세요). | 아니요 |
|
|
심층 연구 설정( | ||||
| 심층 연구를 위한 최대 검색 반복 횟수. | 아니요 |
|
|
| 반복당 최대 검색 쿼리. | 아니요 |
|
|
| 조사를 위해 별도의 브라우저 인스턴스를 사용합니다(
인 경우
가 필요합니다). | 아니요 |
|
|
| 연구 결과물(보고서, 결과)을 저장하는 디렉토리입니다. | 아니요 |
|
|
| 심층 연구 내 하위 에이전트의 최대 단계. | 아니요 |
|
|
브라우저 설정(일반 및 특정 도구 재정의) | ||||
| 새 브라우저를 시작하는 대신
를 통해 사용자 브라우저에 연결하려면 true로 설정합니다. | 아니요 |
|
|
| DevTools 프로토콜 URL을 통해 기존 Chrome에 연결합니다.
인 경우 필수입니다. |
인 경우 | - |
|
| UI 없이 브라우저를 실행합니다. 주로
영향을 미칩니다.
도 참조하세요. | 아니요 |
|
|
| 일반 브라우저 보안 설정입니다.
도 참조하세요. | 아니요 |
|
|
| Chrome/Chromium 실행 파일의 경로입니다. | 아니요 | - |
|
| Chrome 사용자 데이터 디렉터리 경로(영구 세션의 경우
와 함께 사용하면 유용함). | 아니요 | - |
|
| Playwright 추적 파일을 저장하는 디렉토리입니다(디버깅에 유용함). | 아니요 |
|
|
| 브라우저 창 너비(픽셀). | 아니요 |
|
|
| 브라우저 창 높이(픽셀). | 아니요 |
|
|
서버 및 로깅 | ||||
| 서버 로그 파일의 경로입니다. | 아니요 |
|
|
| 로깅 수준(
,
,
,
,
). | 아니요 |
|
|
| 익명화된 원격 측정을 활성화/비활성화합니다(
/
). | 아니요 |
|
|
지원되는 LLM 공급자(
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=9222Windows(명령 프롬프트):
"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 withMCP_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_CDPURL에 접근할 수 있는지 확인하세요(일반적으로 동일한 컴퓨터에서 실행 중인 경우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 - 자세한 내용은 라이센스를 참조하세요.