stagas/browser-mcp-server

Browser MCP Server

A Model Context Protocol (MCP) server that provides browser automation capabilities, specifically for capturing console output from web pages.

Features

• browser-console: Navigate to a URL and capture console output from the browser
• browser-server-console: Spawn a local Express static server for a directory and capture console output from the served content
• Built with Puppeteer for reliable browser automation
• Supports custom timeouts and wait conditions
• Static file serving for local development and testing
• Automatic port detection (finds next available port if requested port is busy)

Installation

npm install

Usage

As an MCP Server

This server is designed to be used with MCP-compatible clients. Add it to your MCP client configuration:

{
  "mcpServers": {
    "browser-mcp-server": {
      "command": "npx",
      "args": ["browser-mcp-server"]
    }
  }
}

Direct Usage

You can also run the server directly:

npm start

Or in development mode with auto-reload:

npm run dev

Tools

browser-console

Navigate to a URL and capture console output from the browser.

Parameters:

• url (required): The URL to navigate to
• timeout (optional): Timeout in milliseconds (default: 30000)
• waitFor (optional): CSS selector to wait for before capturing console
• commands (optional): Browser commands to execute (e.g., "click .button wait 2s")
• stream (optional): Whether to stream output in real-time (default: true)

Commands syntax:

• wait <time>: Wait for specified time (e.g., "5s", "1000ms")
• click <selector>: Click on element matching CSS selector

Example:

{
  "name": "browser-console",
  "arguments": {
    "url": "https://example.com",
    "timeout": 10000,
    "waitFor": "#main-content",
    "commands": "click .load-more-btn wait 2s click .submit",
    "stream": true
  }
}

browser-server-console

Spawn an Express static server for a directory and capture console output from the served content.

Parameters:

• directory (required): The directory to serve statically
• port (optional): Preferred port to run the server on (will automatically find next available if busy, default: 3000)
• path (optional): Path to navigate to after starting server (default: "/")
• timeout (optional): Timeout in milliseconds (default: 30000)
• waitFor (optional): CSS selector to wait for before capturing console
• commands (optional): Browser commands to execute (e.g., "click .button wait 2s")
• stream (optional): Whether to stream output in real-time (default: true)

Commands syntax:

• wait <time>: Wait for specified time (e.g., "5s", "1000ms")
• click <selector>: Click on element matching CSS selector

Example:

{
  "name": "browser-server-console",
  "arguments": {
    "directory": "./public",
    "port": 3001,
    "path": "/index.html",
    "timeout": 10000,
    "waitFor": "#app",
    "commands": "click #start-btn wait 3s",
    "stream": false
  }
}

Implementation Status

• Basic MCP server structure
• Tool schema definition
• Browser navigation with Puppeteer
• Console output capture
• Real-time console message streaming
• Browser command execution (click, wait)
• Error handling for browser issues
• Support for custom timeouts and wait conditions
• True streaming output (currently batched)
• Support for different browser types

Development

The main server implementation is in src/index.js. The current implementation includes:

• MCP server setup with proper tool registration
• Input validation for the browser-console tool
• Error handling and graceful shutdown
• Placeholder implementation for browser functionality

Dependencies

• @modelcontextprotocol/sdk: MCP SDK for server implementation
• puppeteer: Browser automation library for console capture
• express: Web framework for static file serving
• @types/node: TypeScript definitions for Node.js

License

MIT