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

$3

Linux / macOS / Git Bash:

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

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

`cmd


With remote CDP browser


set CDP_ENDPOINT=http://localhost:9222 && npx @coofly/agent-browser-mcp
`

$3

`bash


Clone the repository

git clone
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

$3

`bash


In terminal: Stdio mode (waits for MCP input)

npm start

Via pipe: use Stdio for direct integration

echo '{}' | npm start
`

$3

`bash


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.

$3

When running in HTTP mode, HTTP is available at:

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

$3

`bash


Start Chrome with remote debugging

chrome --remote-debugging-port=9222

Start MCP server with CDP

CDP_ENDPOINT="http://localhost:9222" npm start
`

$3

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

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

With CDP endpoint:

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

Docker

$3

`bash


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
`

$3

`yaml
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
`

$3

`bash


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