agent-browser-mcp

English | 中文

MCP (Model Context Protocol) server for agent-browser - headless browser automation for AI agents.

Features

• CDP Remote Connection: Connect to remote Chrome/Edge browser via Chrome DevTools Protocol
• Transport Selection: HTTP when MCP_HOST + MCP_PORT are set; otherwise Stdio
• Streamable HTTP: Uses modern MCP Streamable HTTP transport for better session management
• Environment Variables: Simple configuration via environment variables
• Docker Support: Ready-to-use Dockerfile for containerized deployment

Installation

Via npx (Recommended)

Linux / macOS / Git Bash:

# Run directly (Stdio mode)
npx @coofly/agent-browser-mcp

# With remote CDP browser
CDP_ENDPOINT="http://localhost:9222" npx @coofly/agent-browser-mcp

Windows (PowerShell):

# Run directly (Stdio mode)
npx @coofly/agent-browser-mcp

# With remote CDP browser
$env:CDP_ENDPOINT="http://localhost:9222"; npx @coofly/agent-browser-mcp

Windows (CMD):

# With remote CDP browser
set CDP_ENDPOINT=http://localhost:9222 && npx @coofly/agent-browser-mcp

From Source

# Clone the repository
git clone <repository-url>
cd agent-browser-mcp

# Install dependencies
npm install

# Build
npm run build

Configuration

All configuration is done via environment variables:

| Variable | Description | Default | |----------|-------------|---------| | MCP_PORT | HTTP server port (required with MCP_HOST to enable HTTP mode) | - | | MCP_HOST | HTTP server host (required with MCP_PORT to enable HTTP mode) | - | | CDP_ENDPOINT | CDP remote endpoint URL | - | | BROWSER_TIMEOUT | Command timeout (ms) | 30000 |

Usage

Stdio Mode (Default)

# In terminal: Stdio mode (waits for MCP input)
npm start

# Via pipe: use Stdio for direct integration
echo '{}' | npm start

HTTP Mode

# Both MCP_HOST and MCP_PORT must be set and valid
MCP_HOST=0.0.0.0 MCP_PORT=9223 npm start

If only one of MCP_HOST/MCP_PORT is set, or the port is invalid, the server exits with an error.

HTTP Endpoints

When running in HTTP mode, HTTP is available at:

• MCP Endpoint: http://localhost:9223/mcp
• Health Check: http://localhost:9223/health

With CDP Remote Browser

# Start Chrome with remote debugging
chrome --remote-debugging-port=9222

# Start MCP server with CDP
CDP_ENDPOINT="http://localhost:9222" npm start

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

With CDP endpoint:

{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["@coofly/agent-browser-mcp"],
      "env": {
        "CDP_ENDPOINT": "http://localhost:9222"
      }
    }
  }
}

Docker

Using Docker Hub (Recommended)

# HTTP mode with built-in browser (browser installed on first start)
docker run -d -p 9223:9223 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=9223 \
  coofly/agent-browser-mcp:latest

# HTTP mode with remote CDP browser (faster startup)
docker run -d -p 9223:9223 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=9223 \
  -e CDP_ENDPOINT=http://host.docker.internal:9222 \
  coofly/agent-browser-mcp:latest

# Stdio mode (for direct integration with MCP clients)
docker run -i --rm \
  coofly/agent-browser-mcp:latest

# Custom timeout setting (default: 30000ms)
docker run -d -p 9223:9223 \
  -e BROWSER_TIMEOUT=60000 \
  coofly/agent-browser-mcp:latest

Docker Compose

version: '3.8'
services:
  agent-browser-mcp:
    image: coofly/agent-browser-mcp:latest
    ports:
      - "9223:9223"           # MCP HTTP server port
    environment:
      # - MCP_HOST=0.0.0.0    # HTTP server bind address (required with MCP_PORT)
      # - MCP_PORT=9223       # HTTP server port (required with MCP_HOST)
      # - CDP_ENDPOINT=http://chrome:9222  # Remote browser CDP endpoint
      # - BROWSER_TIMEOUT=30000            # Command timeout in ms

Build from Source

# Build image
docker build -t agent-browser-mcp:latest .

# Run container (HTTP mode)
docker run -d -p 9223:9223 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=9223 \
  agent-browser-mcp:latest

Available Tools

| Tool | Description | |------|-------------| | browser_open | Open a URL | | browser_back | Navigate back | | browser_forward | Navigate forward | | browser_reload | Reload current page | | browser_get_url | Get current URL | | browser_get_title | Get page title | | browser_click | Click an element | | browser_dblclick | Double-click an element | | browser_type | Type text (character by character) | | browser_fill | Fill input field | | browser_clear | Clear input field | | browser_hover | Hover over element | | browser_press | Press keyboard key | | browser_select | Select dropdown option | | browser_check | Check checkbox (preferred for checkboxes, more reliable than click) | | browser_uncheck | Uncheck checkbox (preferred for checkboxes, more reliable than click) | | browser_focus | Focus an element | | browser_snapshot | Get page accessibility snapshot | | browser_get_text | Get element text | | browser_get_html | Get element HTML | | browser_screenshot | Take screenshot | | browser_scroll | Scroll page | | browser_wait | Wait for element or time (ms) | | browser_evaluate | Execute JavaScript code | | browser_close | Close browser |

License

GPL-3.0