Nik-Browser MCP

Локальный MCP-сервер, который даёт LLM собственный независимый Chromium. Браузер, профиль входов и снимки хранятся внутри папки проекта и не смешиваются с вашим обычным Chrome или Edge.

Подходит для Windows 10/11, LM Studio и других MCP-клиентов со стандартным транспортом stdio.

Что умеет

• открывать сайты и вкладки;
• читать текст страниц и находить кнопки, ссылки и поля;
• нажимать кнопки и клавиши;
• заполнять текстовые поля;
• выбирать пункты списков и устанавливать флажки;
• прикреплять файлы и папки на GitHub, Яндекс Диск, Google Drive и другие сайты;
• делать PNG-снимки страниц;
• проверять Git-проекты на типичные секреты;
• дополнительно публиковать репозитории через GitHub CLI.

Что будет создано на компьютере

Внутри папки проекта появятся:

• .venv — отдельное Python-окружение;
• browser-runtime — собственный Chromium;
• browser-profile — cookies и входы на сайты;
• screenshots — снимки страниц.

Все эти каталоги исключены из Git.

Быстрая установка для Windows

Шаг 1. Установите Python

Скачайте Python 3.10 или новее с https://www.python.org/downloads/windows/.

На первом экране установщика отметьте 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 не установлен, скачайте ZIP на странице GitHub через Code → Download ZIP, распакуйте его и откройте PowerShell в распакованной папке.

Шаг 3. Запустите автоматическую установку

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

Скрипт:

1. создаст .venv;
2. установит Python-зависимости;
3. скачает Chromium в browser-runtime;
4. запустит тесты и MCP-handshake;
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 уже есть другие серверы, не удаляйте их. Добавьте только блок "Nik-Browser": {...} внутрь существующего mcpServers, поставив запятую между соседними блоками.

Готовый шаблон также находится в 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. Перед окончательной отправкой покажи выбранный файл.

Для прикрепления используется browser_upload_files с confirm_external_upload=true. Прикрепление не нажимает финальную кнопку отправки автоматически.

Пример загрузки проекта

Открой 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") — установить gh через winget;
3. один раз выполнить gh auth login в обычном PowerShell;
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: в нём находятся cookies и входы.
• Не добавляйте browser-runtime и .venv в Git.
• Разрешайте модели доступ только к нужным каталогам.
• Проверяйте сайт и список файлов перед confirm_external_upload=true.
• Подробнее: SECURITY.md.

Лицензия

MIT — можно использовать, изменять и распространять с сохранением текста лицензии.