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

[x] Basic MCP server structure
[x] Tool schema definition
[x] Browser navigation with Puppeteer
[x] Console output capture
[x] Real-time console message streaming
[x] Browser command execution (click, wait)
[x] Error handling for browser issues
[x] Support for custom timeouts and wait conditions
[x] 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