Nik-Browser MCP

本地 MCP 服务器，为 LLM 提供独立的 Chromium 浏览器。浏览器、登录配置和截图存储在项目文件夹内，不会与您的常规 Chrome 或 Edge 混淆。

适用于 Windows 10/11、LM Studio 以及其他使用标准 stdio 传输协议的 MCP 客户端。

功能

• 打开网站和标签页；

• 读取页面文本，查找按钮、链接和输入框；

• 点击按钮和按键；

• 填写文本输入框；

• 选择下拉列表项和勾选复选框；

• 在 GitHub、Yandex Disk、Google Drive 等网站上传文件和文件夹；

• 生成页面 PNG 截图；

• 检查 Git 项目中的常见密钥；

• 额外通过 GitHub CLI 发布仓库。

Related MCP server: Browser Jet Pilot

将在计算机上创建的内容

项目文件夹内将出现：

• .venv — 独立的 Python 环境；

• browser-runtime — 专属 Chromium 浏览器；

• browser-profile — Cookie 和网站登录信息；

• 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 中已有其他服务器，请勿删除它们。只需将 "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") — 通过 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：其中包含 Cookie 和登录信息。

• 不要将 browser-runtime 和 .venv 添加到 Git。

• 仅允许模型访问必要的目录。

• 在 confirm_external_upload=true 之前检查网站和文件列表。

• 更多信息：SECURITY.md。

许可证

MIT — 可自由使用、修改和分发，但需保留许可证文本。