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)

Related MCP server: MCP Browser Logger

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