Puppeteer MCP Server

A Model Context Protocol (MCP) server that provides browser automation capabilities through Puppeteer and remote CDP connections.

Features

• Remote Browser Control: Connect to remote browser instances via CDP WebSocket
• MCP Tools: Four essential browser automation tools
  • navigate: Navigate to web pages
  • click: Click elements using CSS selectors
  • evaluate: Execute JavaScript in browser context
  • fetch_content: Get current page HTML content
• Multiple Transport Modes: Support for both stdio and HTTP/SSE transport
• Session Management: Automatic browser instance lifecycle management
• Error Handling: Robust error handling with automatic cleanup
• NPX Support: Can be executed directly via npx without installation

Quick Start with NPX

The easiest way to use this server is via npx:

# Basic usage with stdio mode
npx @freelw/puppeteer-mcp-server --project_id <your_project_id> --api_key <your_api_key>

# Start HTTP server
npx @freelw/puppeteer-mcp-server --project_id <your_project_id> --api_key <your_api_key> --http --port 8089

# Enable debug logging
npx @freelw/puppeteer-mcp-server --project_id <your_project_id> --api_key <your_api_key> --debug

# Show help
npx @freelw/puppeteer-mcp-server --help

Installation (Alternative)

If you prefer to install the package locally:

npm install @freelw/puppeteer-mcp-server

Usage

Start the Server

Using NPX (Recommended)

# Basic usage with stdio mode
npx @freelw/puppeteer-mcp-server --project_id <your_project_id> --api_key <your_api_key>

# HTTP server mode
npx @freelw/puppeteer-mcp-server --project_id <your_project_id> --api_key <your_api_key> --http --port 8089

# Enable debug logging
npx @freelw/puppeteer-mcp-server --project_id <your_project_id> --api_key <your_api_key> --debug

# Using short form arguments
npx @freelw/puppeteer-mcp-server -p <your_project_id> -k <your_api_key> [--http] [--port <port>]

Local Installation

# After npm install
node src/server.js --project_id <your_project_id> --api_key <your_api_key>

# HTTP mode
node src/server.js --project_id <your_project_id> --api_key <your_api_key> --http --port 8089

# Using short form arguments
node src/server.js -p <your_project_id> -k <your_api_key> [-u <api_url>] [--http] [--port <port>]

Parameters

• --project_id / -p: Required - Your project ID
• --api_key / -k: Required - Your API key
• --api_url / -u: Optional - API server base URL (defaults to https://api.lexmount.net/)
• --http: Optional - Start HTTP server instead of stdio mode
• --port: Optional - HTTP server port (defaults to 8089)

Environment Variables

Set the API server base URL (optional, defaults to https://api.lexmount.net/):

export API_BASE_URL=https://your-api-server.com

Logging Configuration

Note: Logging is disabled by default. To enable logging, set MCP_DEBUG=1 or use the --debug flag.

# Enable debug logging (logs will be written to ~/.puppeteer-browser/logs/)
export MCP_DEBUG=1

# Or use the --debug flag with npx
npx @freelw/puppeteer-mcp-server --debug --project_id <id> --api_key <key>

When debug logging is enabled, you can control specific log types:

# Disable CDP logs (browser events, requests, responses)
export ENABLE_CDP_LOGS=false

# Disable HTTP logs (API calls)
export ENABLE_HTTP_LOGS=false

# Disable MCP logs (tool calls)
export ENABLE_MCP_LOGS=false

# Disable file logging (only console output)
export ENABLE_FILE_LOGGING=false

MCP Tools

1. Navigate

Navigate to a specific URL.

{
  "name": "navigate",
  "arguments": {
    "url": "https://example.com"
  }
}

2. Click

Click an element using CSS selector.

{
  "name": "click",
  "arguments": {
    "selector": "#submit-button"
  }
}

3. Evaluate

Execute JavaScript code in the browser context.

{
  "name": "evaluate",
  "arguments": {
    "script": "document.title"
  }
}

4. Fetch Content

Get the HTML content of the current page.

{
  "name": "fetch_content",
  "arguments": {}
}

Configuration

The server uses the following configuration (see config.js):

• API Base URL: Set via --api_url parameter or API_BASE_URL environment variable (defaults to https://api.lexmount.net/)
• Connection Timeout: 30 seconds
• Operation Timeout: 60 seconds

Error Handling

The server implements comprehensive error handling:

• Initialization Errors: Fails fast if browser instance cannot be created
• Tool Execution Errors: Returns structured error responses
• Network Errors: Automatic retry and cleanup
• Resource Cleanup: Automatic cleanup on server shutdown

Development

# Run in development mode with auto-restart
npm run dev

# Run normally
npm start

API Requirements

This server requires a compatible API server that provides:

1. POST /instance - Create browser instance
2. DELETE /instance - Delete browser instance
3. GET /json/version?session_id={session_id} - Get CDP connection URL

See plan/API.md for detailed API specifications.