Nik-Browser MCP

Servidor MCP local que proporciona a la LLM su propio Chromium independiente. El navegador, el perfil de inicios de sesión y las capturas de pantalla se almacenan dentro de la carpeta del proyecto y no se mezclan con su Chrome o Edge habitual.

Adecuado para Windows 10/11, LM Studio y otros clientes MCP con transporte stdio estándar.

Qué puede hacer

• Abrir sitios web y pestañas;

• Leer el texto de las páginas y encontrar botones, enlaces y campos;

• Pulsar botones y teclas;

• Rellenar campos de texto;

• Seleccionar elementos de listas y marcar casillas;

• Adjuntar archivos y carpetas en GitHub, Yandex Disk, Google Drive y otros sitios;

• Hacer capturas de pantalla PNG de las páginas;

• Revisar proyectos Git en busca de secretos típicos;

• Publicar repositorios adicionalmente mediante GitHub CLI.

Related MCP server: Browser Jet Pilot

Qué se creará en el ordenador

Dentro de la carpeta del proyecto aparecerán:

• .venv — un entorno Python separado;

• browser-runtime — su propio Chromium;

• browser-profile — cookies e inicios de sesión en sitios web;

• screenshots — capturas de pantalla.

Todos estos directorios están excluidos de Git.

Instalación rápida para Windows

Paso 1. Instale Python

Descargue Python 3.10 o superior desde https://www.python.org/downloads/windows/.

En la primera pantalla del instalador, marque Add Python to PATH.

Paso 2. Descargue el proyecto

Abra PowerShell y ejecute:

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

Si Git no está instalado, descargue el ZIP en la página de GitHub mediante Code → Download ZIP, descomprímalo y abra PowerShell en la carpeta descomprimida.

Paso 3. Ejecute la instalación automática

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

El script:

1. creará .venv;

2. instalará las dependencias de Python;

3. descargará Chromium en browser-runtime;

4. ejecutará las pruebas y el handshake MCP;

5. imprimirá el fragmento de configuración listo.

Instalación manual de venv

Si el script automático no le sirvió:

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

Si py -3.10 no se encuentra, pruebe con py -3.

Chromium se puede instalar después de la conexión, pidiéndole al modelo que ejecute:

browser_install_runtime с confirm="INSTALL_BROWSER"

O instalarlo de antemano:

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

Conexión a LM Studio

Paso 1. Obtenga la ruta completa

En PowerShell, estando en la carpeta del proyecto:

$PWD.Path

Por ejemplo, obtuvo:

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

Paso 2. Abra la configuración de MCP

En LM Studio, abra la sección MCP Servers o el archivo:

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

Paso 3. Agregue el servidor

Reemplace C:\PATH\TO\nik-browser-mcp por la ruta completa real:

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

Si en mcp.json ya hay otros servidores, no los elimine. Agregue solo el bloque "Nik-Browser": {...} dentro del mcpServers existente, colocando una coma entre los bloques adyacentes.

La plantilla lista también se encuentra en mcp.example.json.

Después de guardar, actualice la lista de MCP, desactive y active el servidor, o reinicie LM Studio.

Primer inicio

Escriba al modelo:

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

Se abrirá una ventana separada de Chromium. Inicie sesión en los servicios necesarios manualmente. Los inicios de sesión se guardarán en browser-profile.

Cómo usarlo

El modelo debe trabajar en el siguiente orden:

1. browser_snapshot — obtener el texto de la página y los elementos e1, e2, etc.

2. browser_click, browser_fill, browser_select_option o browser_set_checked — realizar la acción.

3. Después de navegar a otra página — volver a llamar a browser_snapshot.

Los identificadores e1, e2 son temporales. El error Ref expired significa que se necesita una nueva captura.

Ejemplo de búsqueda

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

Ejemplo de carga de archivo

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

Para adjuntar se usa browser_upload_files con confirm_external_upload=true. El adjunto no pulsa automáticamente el botón final de envío.

Ejemplo de carga de proyecto

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

Al cargar una carpeta, se omiten automáticamente .git, .venv, venv, node_modules y __pycache__. Los secretos típicos y las claves privadas están bloqueados.

Publicación en GitHub

Los archivos pequeños se pueden cargar a través del sitio web de GitHub con las herramientas habituales del navegador.

Para un repositorio Git completo, es más conveniente una vía adicional mediante GitHub CLI:

1. github_cli_status — verificar la instalación y el inicio de sesión;

2. github_cli_install(confirm="INSTALL_GH") — instalar gh mediante winget;

3. ejecutar gh auth login una vez en PowerShell normal;

4. git_project_status — verificar el proyecto y los secretos;

5. github_publish_project(..., confirm="PUBLISH") — crear y enviar el repositorio.

Por defecto, use visibility="private". Para un proyecto público, especifique visibility="public" explícitamente.

Verificación de la instalación

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

Un resultado exitoso contiene una línea como:

MCP handshake OK: 19 tools

Errores frecuentes

Not connected

• Verifique las rutas absolutas en command y args;

• Verifique que exista .venv\Scripts\python.exe;

• Ejecute smoke_test.py;

• Desactive y vuelva a activar MCP;

• Si no funciona, reinicie LM Studio.

Private browser runtime is not installed

Ejecute:

browser_install_runtime(confirm="INSTALL_BROWSER")

Browser did not expose CDP

El puerto 9333 está ocupado por otro proceso. Cierre la ventana anterior de Nik-Browser o especifique el mismo puerto libre en MCP_BROWSER_CDP_URL y browser_launch.

Path is outside MCP_BROWSER_ALLOWED_ROOTS

Agregue la carpeta necesaria a MCP_BROWSER_ALLOWED_ROOTS. En Windows, las rutas se separan con punto y coma. Después del cambio, reinicie MCP.

Seguridad

• CDP solo está disponible a través de localhost.

• Nunca publique browser-profile: contiene cookies e inicios de sesión.

• No agregue browser-runtime ni .venv a Git.

• Permita que el modelo acceda solo a los directorios necesarios.

• Verifique el sitio y la lista de archivos antes de confirm_external_upload=true.

• Más información: SECURITY.md.

Licencia

MIT — se puede usar, modificar y distribuir manteniendo el texto de la licencia.