npm package: @freelw/puppeteer-mcp-server
Description: Puppeteer MCP Server for remote browser automation
Latest version: 1.1.2

# 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`:

```bash
# 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:

```bash
npm install @freelw/puppeteer-mcp-server
```

## Usage

### Start the Server

#### Using NPX (Recommended)

```bash
# 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

```bash
# 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/`):

```bash
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.

```bash
# 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:

```bash
# 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.

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

#### 2. Click
Click an element using CSS selector.

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

#### 3. Evaluate
Execute JavaScript code in the browser context.

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

#### 4. Fetch Content
Get the HTML content of the current page.

```json
{
  "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

```bash
# 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.