Browser MCP Bridge

Dale a Claude Code acceso directo a tu navegador. Inspecciona páginas, lee errores de consola, supervisa solicitudes de red, captura capturas de pantalla y ejecuta JavaScript, todo mediante lenguaje natural.

Qué hace esto

Browser MCP Bridge conecta tu navegador Chrome con Claude Code a través del Protocolo de Contexto de Modelo (MCP). Consta de dos partes:

1. Una extensión de Chrome que captura datos del navegador (contenido de la página, DOM, consola, red, rendimiento, accesibilidad)

2. Un servidor MCP que expone esos datos a Claude Code a través de 11 herramientas especializadas

Una vez conectado, puedes pedirle a Claude Code cosas como:

• "Comprueba si esta página tiene problemas de accesibilidad"

• "¿Qué errores de consola hay en esta página?"

• "Muéstrame las solicitudes API fallidas"

• "Analiza el rendimiento de esta página"

• "Ejecuta document.querySelectorAll('a') en la página actual"

Related MCP server: Browser Tools for Claude Code

Inicio rápido

Empieza en menos de 5 minutos:

1. Instala el servidor

git clone https://github.com/anthropics/browser-mcp-bridge.git
cd browser-mcp-bridge
npm run install-server

2. Instala la extensión del navegador

1. Abre chrome://extensions/ (o edge://extensions/)

2. Habilita el Modo de desarrollador (interruptor en la parte superior derecha)

3. Haz clic en Cargar descomprimida

4. Selecciona el directorio extension/ de este repositorio

Deberías ver el icono de "Browser MCP Bridge" en tu barra de herramientas.

3. Configura Claude Code

claude mcp add --scope user --transport http browser-mcp http://127.0.0.1:6009/mcp

4. Inicia el servidor y conéctate

npm start

Luego haz clic en el icono de la extensión Browser MCP Bridge y haz clic en Connect. El indicador de estado debería ponerse en verde.

Eso es todo: Claude Code ahora tiene acceso a tu navegador.

Estructura del proyecto

browser-mcp-bridge/
├── extension/                 # Chrome extension
│   ├── manifest.json          # Manifest V3 configuration
│   ├── background.js          # Service worker (WebSocket, tab management)
│   ├── content.js             # Content script (page data extraction)
│   ├── inject.js              # Injected script (console/network interception)
│   ├── popup.html/js          # Extension popup (connection management)
│   ├── devtools.html/js       # DevTools integration entry point
│   ├── panel.html/js          # Custom DevTools panel UI
│   └── icons/                 # Extension icons
├── server/                    # Node.js MCP server
│   ├── server.js              # HTTP MCP server + WebSocket server
│   └── package.json           # Server dependencies
├── rust-server/               # Rust MCP server (experimental)
│   ├── src/                   # Rust source code
│   ├── Cargo.toml             # Rust dependencies
│   └── config.toml            # Server configuration
├── browser-mcp-rust-server.service  # systemd user service unit
├── install-rust-service.sh          # Service install/uninstall script
├── start-rust-server.sh             # PM2 launch script for Rust server
├── ecosystem.config.cjs             # PM2 process manager config
├── ARCHITECTURE.md                  # System architecture documentation
├── API_REFERENCE.md           # Complete MCP tools reference
├── DATA_OPTIMIZATION.md       # Data filtering and pagination guide
└── package.json               # Root scripts and orchestration

Cómo funciona

┌─────────────────┐     WebSocket      ┌──────────────────┐      HTTP/MCP      ┌─────────────────┐
│ Chrome Extension │ ◄──────────────── │  MCP Server      │ ◄──────────────── │  Claude Code     │
│                  │   ws://localhost   │  (port 6009)     │   http://localhost │  (one or more    │
│  • content.js    │      :6009/ws     │                  │      :6009/mcp    │   instances)     │
│  • background.js │ ─────────────────►│  • 11 MCP tools  │ ─────────────────►│                  │
│  • inject.js     │                   │  • Resources     │                   │                  │
│  • DevTools      │                   │  • Data filtering│                   │                  │
└─────────────────┘                    └──────────────────┘                    └─────────────────┘

1. La extensión captura datos del navegador a través de scripts de contenido y APIs de Chrome

2. Una conexión WebSocket envía datos al servidor MCP en el puerto 6009

3. Claude Code se conecta al servidor a través del transporte HTTP en /mcp

4. Múltiples instancias de Claude Code pueden compartir el mismo servidor

Herramientas disponibles

Todas las herramientas admiten un parámetro opcional tabId para dirigirse a una pestaña específica. Consulta API_REFERENCE.md para obtener la documentación completa de los parámetros.

Flujos de trabajo de ejemplo

Depuración de errores de consola

Pregúntale a Claude Code: "¿Qué errores se muestran en la consola del navegador?"

Claude Code utilizará get_console_messages para recuperar errores y advertencias, luego los analizará y sugerirá correcciones.

Análisis de llamadas API fallidas

Pregunta: "Muéstrame las solicitudes de red fallidas y ayúdame a depurarlas"

Claude Code utiliza get_network_requests con filtrado de solo fallos para encontrar respuestas 4xx/5xx, luego inspecciona los cuerpos de solicitud/respuesta en busca de pistas.

Auditoría de accesibilidad

Pregunta: "Comprueba esta página en busca de problemas de accesibilidad"

Claude Code llama a get_accessibility_tree y get_page_content para analizar atributos ARIA, estructura de encabezados, texto alternativo y HTML semántico.

Análisis de rendimiento

Pregunta: "¿Cómo es el rendimiento de esta página? ¿Algún problema?"

Utiliza get_performance_metrics y get_network_requests para identificar recursos lentos, cargas útiles grandes y problemas de Core Web Vitals.

Inspección visual

Pregunta: "Toma una captura de pantalla de la página actual"

capture_screenshot devuelve una instantánea PNG o JPEG de la pestaña visible.

Configuración

Puerto del servidor

El servidor utiliza el puerto 6009 por defecto. Para usar un puerto diferente:

MCP_SERVER_PORT=8080 npm start

Si cambias el puerto, actualiza la URL de WebSocket de la extensión en la ventana emergente (ws://localhost:8080/ws) y tu configuración de MCP de Claude Code.

Configuración de la extensión

Haz clic en el icono de la extensión para:

• Ver el estado de la conexión

• Cambiar la URL del servidor WebSocket

• Activar manualmente la captura de datos

• Ver estadísticas de mensajes

Ejecución con PM2 (Producción)

# Start with PM2
npm run pm2:start

# Other PM2 commands
npm run pm2:status    # Check status
npm run pm2:logs      # View logs
npm run pm2:restart   # Restart
npm run pm2:stop      # Stop

Consulta PM2_GUIDE.md para el inicio automático al arrancar y la configuración avanzada.

Ejecución del servidor Rust con systemd (Linux)

El servidor Rust puede gestionarse como un servicio de usuario de systemd para el inicio automático y la supervisión de procesos.

Configuración rápida:

# Build and install the service in one step
./install-rust-service.sh

# Or install without rebuilding (if you already have a release binary)
./install-rust-service.sh --no-build

Gestión del servicio:

systemctl --user status browser-mcp-rust-server     # Check status
journalctl --user -u browser-mcp-rust-server -f      # Follow logs
systemctl --user restart browser-mcp-rust-server     # Restart
systemctl --user stop browser-mcp-rust-server        # Stop

El servicio se inicia automáticamente al iniciar sesión. Para iniciarlo incluso sin una sesión de inicio de sesión (útil para acceso headless/SSH):

loginctl enable-linger $USER

Desinstalación:

./install-rust-service.sh --uninstall

Instalación manual (si prefieres no usar el script):

# Build the release binary
cd rust-server && cargo build --release

# Copy the service file
mkdir -p ~/.config/systemd/user
cp browser-mcp-rust-server.service ~/.config/systemd/user/

# If your repo is NOT at ~/dev/browser-mcp-bridge, edit the paths:
#   systemctl --user edit browser-mcp-rust-server
# and override ExecStart and WorkingDirectory

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now browser-mcp-rust-server

Configuración:

El servicio lee rust-server/config.toml por defecto. Para cambiar el puerto u otros ajustes, edita config.toml y reinicia:

systemctl --user restart browser-mcp-rust-server

Establece RUST_LOG para la verbosidad del registro. El valor predeterminado es info. Sobrescríbelo con un archivo drop-in:

systemctl --user edit browser-mcp-rust-server

[Service]
Environment=RUST_LOG=debug

Configuración de MCP para otros clientes

Para clientes MCP que utilizan configuración JSON:

{
  "mcpServers": {
    "browser-mcp": {
      "url": "http://localhost:6009/mcp"
    }
  }
}

Desarrollo

Desarrollo del servidor

npm run dev          # Start with --watch (auto-restart on changes)
DEBUG=* npm start    # Verbose logging

Desarrollo de la extensión

1. Realiza cambios en los archivos en extension/

2. Ve a chrome://extensions/

3. Haz clic en el botón de recarga en la extensión Browser MCP Bridge

Comprobación de estado

npm run health-check
# or: curl http://localhost:6009/health

Adición de nuevas herramientas

1. Añade la definición de la herramienta en server.js → manejador ListToolsRequestSchema

2. Implementa la lógica de la herramienta en server.js → manejador CallToolRequestSchema

3. Añade el manejador del lado del navegador en extension/background.js

4. Prueba con Claude Code

Optimización de datos

El servidor implementa valores predeterminados inteligentes para mantener las respuestas manejables para los agentes de IA:

• HTML: Truncado a 50KB (texto a 30KB)

• DOM: Limitado a 500 nodos, scripts/estilos excluidos

• Consola: Devuelve errores y advertencias por defecto

• Red: 50 solicitudes, solicitudes fallidas ordenadas primero, cuerpos excluidos

Todos los límites son configurables por solicitud. Consulta DATA_OPTIMIZATION.md para obtener la guía completa de filtrado, paginación y optimización.

Solución de problemas

La extensión no se conecta

1. Verifica que el servidor esté ejecutándose: curl http://localhost:6009/health

2. Comprueba que la URL de WebSocket en la ventana emergente de la extensión coincida con el puerto del servidor

3. Busca errores en la consola del navegador (chrome://extensions/ → enlace de errores)

Claude Code no puede encontrar las herramientas

1. Verifica la configuración de MCP: claude mcp list

2. Comprueba que el servidor esté ejecutándose y en buen estado

3. Vuelve a añadir el servidor: claude mcp remove browser-mcp && claude mcp add --scope user --transport http browser-mcp http://127.0.0.1:6009/mcp

No se devuelven datos de las herramientas

1. Asegúrate de que la extensión esté conectada (estado verde en la ventana emergente)

2. Navega a una página en el navegador: la extensión necesita una página activa

3. Comprueba si el ID de la pestaña es correcto (usa get_browser_tabs primero)

El servidor no arranca

1. Comprueba la versión de Node.js: node --version (requiere 18.0.0+)

2. Instala dependencias: npm run install-server

3. Comprueba si el puerto 6009 está en uso: lsof -i :6009

Lecturas adicionales

• ARCHITECTURE.md — Diseño del sistema, flujo de datos y detalles de los componentes

• API_REFERENCE.md — Referencia completa de herramientas MCP con todos los parámetros

• DATA_OPTIMIZATION.md — Filtrado, paginación y ajuste de rendimiento

Requisitos

• Node.js 18.0.0+

• Chrome, Edge o navegador basado en Chromium

• Claude Code CLI (o cualquier cliente compatible con MCP)

Licencia

MIT