Nik-Browser MCP

A local MCP server that gives LLMs their own independent Chromium. The browser, login profile, and screenshots are stored inside the project folder and do not mix with your regular Chrome or Edge.

Suitable for Windows 10/11, LM Studio, and other MCP clients using the standard stdio transport.

Features

• Open websites and tabs;

• Read page text and find buttons, links, and fields;

• Click buttons and press keys;

• Fill in text fields;

• Select list items and set checkboxes;

• Attach files and folders to GitHub, Yandex Disk, Google Drive, and other sites;

• Take PNG screenshots of pages;

• Check Git projects for common secrets;

• Additionally publish repositories via GitHub CLI.

Related MCP server: mare-browser-mcp

What Will Be Created on Your Computer

Inside the project folder, the following will appear:

• .venv — a separate Python environment;

• browser-runtime — its own Chromium;

• browser-profile — cookies and site logins;

• screenshots — page screenshots.

All these directories are excluded from Git.

Quick Installation for Windows

Step 1. Install Python

Download Python 3.10 or newer from https://www.python.org/downloads/windows/.

On the first installer screen, check Add Python to PATH.

Step 2. Download the Project

Open PowerShell and run:

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

If Git is not installed, download the ZIP from the GitHub page via Code → Download ZIP, unzip it, and open PowerShell in the unzipped folder.

Step 3. Run the Automatic Installation

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

The script will:

1. Create .venv;

2. Install Python dependencies;

3. Download Chromium into browser-runtime;

4. Run tests and the MCP handshake;

5. Print a ready configuration snippet.

Manual venv Installation

If the automatic script is not suitable:

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

If py -3.10 is not found, try py -3.

Chromium can be installed after connecting by asking the model to call:

browser_install_runtime с confirm="INSTALL_BROWSER"

Or install it in advance:

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

Connecting to LM Studio

Step 1. Find the Full Path

In PowerShell, while in the project folder:

$PWD.Path

For example, the result might be:

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

Step 2. Open the MCP Configuration

In LM Studio, open the MCP Servers section or the file:

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

Step 3. Add the Server

Replace C:\PATH\TO\nik-browser-mcp with the actual full path:

{
  "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"
      }
    }
  }
}

If mcp.json already contains other servers, do not delete them. Only add the "Nik-Browser": {...} block inside the existing mcpServers, placing a comma between adjacent blocks.

A ready template is also available in mcp.example.json.

After saving, refresh the MCP list, turn the server off and on, or restart LM Studio.

First Launch

Ask the model:

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

A separate Chromium window will open. Log into the required services manually. Logins will be saved in browser-profile.

How to Use

The model should work in this order:

1. browser_snapshot — get the page text and elements e1, e2, and so on.

2. browser_click, browser_fill, browser_select_option, or browser_set_checked — perform an action.

3. After navigating to another page, call browser_snapshot again.

Identifiers e1, e2 are temporary. A Ref expired error means a new snapshot is needed.

Search Example

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

File Upload Example

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

Use browser_upload_files with confirm_external_upload=true for attaching. Attaching does not automatically click the final submit button.

Project Upload Example

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

When uploading a folder, .git, .venv, venv, node_modules, and __pycache__ are automatically skipped. Common secrets and private keys are blocked.

Publishing to GitHub

Small files can be uploaded via the GitHub website using standard browser tools.

For a full Git repository, an additional path via GitHub CLI is more convenient:

1. github_cli_status — check installation and login;

2. github_cli_install(confirm="INSTALL_GH") — install gh via winget;

3. run gh auth login once in a regular PowerShell;

4. git_project_status — check the project and secrets;

5. github_publish_project(..., confirm="PUBLISH") — create and push the repository.

By default, use visibility="private". For a public project, explicitly specify visibility="public".

Installation Check

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

A successful result contains a line like:

MCP handshake OK: 19 tools

Common Errors

Not connected

• Check the absolute paths in command and args;

• Check that .venv\Scripts\python.exe exists;

• Run smoke_test.py;

• Turn MCP off and on again;

• If that doesn't help, restart LM Studio.

Private browser runtime is not installed

Call:

browser_install_runtime(confirm="INSTALL_BROWSER")

Browser did not expose CDP

Port 9333 is occupied by another process. Close the old Nik-Browser window or specify the same free port in MCP_BROWSER_CDP_URL and browser_launch.

Path is outside MCP_BROWSER_ALLOWED_ROOTS

Add the required folder to MCP_BROWSER_ALLOWED_ROOTS. On Windows, paths are separated by semicolons. Restart MCP after making the change.

Security

• CDP is only accessible via localhost.

• Never publish browser-profile: it contains cookies and logins.

• Do not add browser-runtime and .venv to Git.

• Only grant the model access to the necessary directories.

• Check the site and file list before using confirm_external_upload=true.

• More details: SECURITY.md.

License

MIT — you can use, modify, and distribute it while retaining the license text.