Nik-Browser MCP

로컬 MCP 서버로, LLM에 독립적인 Chromium을 제공합니다. 브라우저, 로그인 프로필 및 스크린샷은 프로젝트 폴더 내에 저장되며 일반 Chrome이나 Edge와 섞이지 않습니다.

Windows 10/11, LM Studio 및 표준 stdio 전송 방식을 사용하는 기타 MCP 클라이언트에 적합합니다.

기능

• 사이트 및 탭 열기;

• 페이지 텍스트 읽기 및 버튼, 링크, 필드 찾기;

• 버튼 및 키 누르기;

• 텍스트 필드 채우기;

• 목록 항목 선택 및 체크박스 설정;

• GitHub, Яндекс Диск, Google Drive 및 기타 사이트에 파일 및 폴더 첨부;

• PNG 페이지 스크린샷 촬영;

• Git 프로젝트에서 일반적인 비밀 정보 확인;

• GitHub CLI를 통해 추가로 리포지토리 게시.

Related MCP server: Browser Jet Pilot

컴퓨터에 생성되는 항목

프로젝트 폴더 내에 다음이 생성됩니다:

• .venv — 별도의 Python 환경;

• browser-runtime — 자체 Chromium;

• browser-profile — 쿠키 및 사이트 로그인 정보;

• screenshots — 페이지 스크린샷.

이 모든 디렉터리는 Git에서 제외됩니다.

Windows 빠른 설치

1단계. Python 설치

https://www.python.org/downloads/windows/에서 Python 3.10 이상을 다운로드하세요.

설치 프로그램의 첫 화면에서 Add Python to PATH를 체크하세요.

2단계. 프로젝트 다운로드

PowerShell을 열고 다음을 실행하세요:

cd "$HOME\Desktop"
git clone https://github.com/Nikolay-3D/nik-browser-mcp.git
cd nik-browser-mcp

Git이 설치되어 있지 않으면 GitHub 페이지에서 Code → Download ZIP을 통해 ZIP을 다운로드하고 압축을 푼 다음, 압축을 푼 폴더에서 PowerShell을 여세요.

3단계. 자동 설치 실행

powershell -ExecutionPolicy Bypass -File .\install-windows.ps1

스크립트는:

1. .venv를 생성합니다;

2. Python 종속성을 설치합니다;

3. Chromium을 browser-runtime에 다운로드합니다;

4. 테스트 및 MCP 핸드셰이크를 실행합니다;

5. 완성된 구성 조각을 출력합니다.

수동 venv 설치

자동 스크립트가 작동하지 않는 경우:

cd "ПОЛНЫЙ\ПУТЬ\К\nik-browser-mcp"
py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

py -3.10을 찾을 수 없으면 py -3을 시도해 보세요.

Chromium은 연결 후 모델에 다음을 요청하여 설치할 수 있습니다:

browser_install_runtime с confirm="INSTALL_BROWSER"

또는 미리 설치할 수 있습니다:

$env:PLAYWRIGHT_BROWSERS_PATH = "$PWD\browser-runtime"
.\.venv\Scripts\python.exe -m playwright install chromium

LM Studio에 연결

1단계. 전체 경로 확인

PowerShell에서 프로젝트 폴더에 있는 상태로:

$PWD.Path

예를 들어, 다음과 같이 출력됩니다:

C:\Users\Ivan\Desktop\nik-browser-mcp

2단계. MCP 구성 열기

LM Studio에서 MCP Servers 섹션 또는 다음 파일을 여세요:

C:\Users\ВАШЕ_ИМЯ\.lmstudio\mcp.json

3단계. 서버 추가

C:\PATH\TO\nik-browser-mcp를 실제 전체 경로로 바꾸세요:

{
  "mcpServers": {
    "Nik-Browser": {
      "command": "C:\\PATH\\TO\\nik-browser-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\PATH\\TO\\nik-browser-mcp\\run_server.py"
      ],
      "env": {
        "MCP_BROWSER_CDP_URL": "http://127.0.0.1:9333",
        "MCP_BROWSER_ALLOWED_ROOTS": "C:\\Users\\ВАШЕ_ИМЯ\\Desktop;C:\\Users\\ВАШЕ_ИМЯ\\Documents;C:\\Users\\ВАШЕ_ИМЯ\\Downloads",
        "PYTHONUTF8": "1"
      }
    }
  }
}

mcp.json에 이미 다른 서버가 있는 경우 삭제하지 마세요. 기존 mcpServers 내부에 "Nik-Browser": {...} 블록만 추가하고, 인접한 블록 사이에 쉼표를 넣으세요.

완성된 템플릿은 mcp.example.json에도 있습니다.

저장 후 MCP 목록을 새로고침하고 서버를 껐다 켜거나 LM Studio를 다시 시작하세요.

첫 실행

모델에 다음과 같이 요청하세요:

Запусти собственный браузер через browser_launch, открой github.com и покажи список вкладок.

별도의 Chromium 창이 열립니다. 필요한 서비스에 수동으로 로그인하세요. 로그인 정보는 browser-profile에 저장됩니다.

사용 방법

모델은 다음 순서로 작업해야 합니다:

1. browser_snapshot — 페이지 텍스트와 e1, e2 등의 요소를 가져옵니다.

2. browser_click, browser_fill, browser_select_option 또는 browser_set_checked — 작업을 수행합니다.

3. 다른 페이지로 이동한 후에는 다시 browser_snapshot을 호출합니다.

e1, e2 식별자는 임시적입니다. Ref expired 오류는 새 스냅샷이 필요함을 의미합니다.

검색 예시

Открой сайт, найди поле поиска, введи запрос и покажи результаты.

파일 업로드 예시

Открой Яндекс Диск, найди загрузку и прикрепи файл C:\Users\Ivan\Desktop\report.pdf. Перед окончательной отправкой покажи выбранный файл.

첨부에는 confirm_external_upload=true와 함께 browser_upload_files가 사용됩니다. 첨부는 최종 전송 버튼을 자동으로 누르지 않습니다.

프로젝트 업로드 예시

Открой Google Drive и загрузи папку C:\Users\Ivan\Desktop\MyProject. Не отправляй ничего, пока не покажешь список файлов.

폴더 업로드 시 .git, .venv, venv, node_modules 및 __pycache__는 자동으로 건너뜁니다. 일반적인 비밀 정보와 개인 키는 차단됩니다.

GitHub에 게시

작은 파일은 일반 브라우저 도구를 통해 GitHub 사이트에 업로드할 수 있습니다.

전체 Git 리포지토리의 경우 GitHub CLI를 통한 추가 경로가 더 편리합니다:

1. github_cli_status — 설치 및 로그인 확인;

2. github_cli_install(confirm="INSTALL_GH") — winget을 통해 gh 설치;

3. 일반 PowerShell에서 gh auth login을 한 번 실행;

4. git_project_status — 프로젝트 및 비밀 정보 확인;

5. github_publish_project(..., confirm="PUBLISH") — 리포지토리 생성 및 푸시.

기본적으로 visibility="private"을 사용하세요. 공개 프로젝트의 경우 명시적으로 visibility="public"을 지정하세요.

설치 확인

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe smoke_test.py

성공적인 결과에는 다음과 같은 줄이 포함됩니다:

MCP handshake OK: 19 tools

자주 발생하는 오류

Not connected

• command 및 args의 절대 경로를 확인하세요;

• .venv\Scripts\python.exe의 존재를 확인하세요;

• smoke_test.py를 실행하세요;

• MCP를 껐다가 다시 켜세요;

• 그래도 해결되지 않으면 LM Studio를 다시 시작하세요.

Private browser runtime is not installed

다음을 호출하세요:

browser_install_runtime(confirm="INSTALL_BROWSER")

Browser did not expose CDP

포트 9333이 다른 프로세스에서 사용 중입니다. 이전 Nik-Browser 창을 닫거나, MCP_BROWSER_CDP_URL과 browser_launch에 동일한 사용 가능한 포트를 지정하세요.

Path is outside MCP_BROWSER_ALLOWED_ROOTS

필요한 폴더를 MCP_BROWSER_ALLOWED_ROOTS에 추가하세요. Windows에서 경로는 세미콜론으로 구분됩니다. 변경 후 MCP를 다시 시작하세요.

보안

• CDP는 localhost를 통해서만 액세스할 수 있습니다.

• browser-profile을 절대 게시하지 마세요. 여기에는 쿠키와 로그인 정보가 포함되어 있습니다.

• browser-runtime과 .venv를 Git에 추가하지 마세요.

• 모델에 필요한 디렉터리만 허용하세요.

• confirm_external_upload=true 전에 사이트와 파일 목록을 확인하세요.

• 자세한 내용: SECURITY.md.

라이선스

MIT — 라이선스 텍스트를 유지하는 조건으로 사용, 수정 및 배포할 수 있습니다.