Content
# Browser MCP
A Model Context Protocol (MCP) server for browser automation using Puppeteer. This enables AI assistants like Claude, GPT, and other LLM-powered tools to navigate web pages, take screenshots, click elements, fill forms, and interact with web content.
## Features
- **Navigation**: Navigate to URLs, go back/forward, reload pages
- **Screenshots**: Capture full-page or viewport screenshots
- **Interaction**: Click, type, hover, scroll, select dropdown options
- **Content Extraction**: Get page content, titles, and links
- **JavaScript Execution**: Run custom scripts in the browser context
- **Wait Conditions**: Wait for elements or timeouts
## Installation
### Prerequisites
- Node.js 18+ (LTS recommended)
- npm, pnpm, or bun
### Install via npx (Recommended)
You can run the server directly without installation:
```bash
npx github:blink-new/browser-mcp
```
### Install Globally
```bash
npm install -g github:blink-new/browser-mcp
```
### Install from Source
```bash
git clone https://github.com/blink-new/browser-mcp.git
cd browser-mcp
npm install
npm run build
```
## Setup Instructions
### Ubuntu / Debian Linux
1. **Install Node.js 18+**:
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```
2. **Install Chromium dependencies**:
```bash
sudo apt-get install -y \
libnss3 \
libatk1.0-0 \
libatk-bridge2.0-0 \
libcups2 \
libdrm2 \
libxkbcommon0 \
libxcomposite1 \
libxdamage1 \
libxfixes3 \
libxrandr2 \
libgbm1 \
libasound2 \
libpango-1.0-0 \
libcairo2 \
libatspi2.0-0
```
3. **Configure your MCP client** (see Configuration section below)
### macOS
1. **Install Node.js 18+** (using Homebrew):
```bash
brew install node
```
Or using nvm:
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20
```
2. **Configure your MCP client** (see Configuration section below)
### Windows
1. **Install Node.js 18+**:
- Download and install from [nodejs.org](https://nodejs.org/)
- Or use winget: `winget install OpenJS.NodeJS.LTS`
2. **Configure your MCP client** (see Configuration section below)
## Configuration
### OpenCode
Add to your `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"browser": {
"type": "local",
"command": ["npx", "-y", "github:blink-new/browser-mcp"],
"enabled": true
}
}
}
```
### Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["-y", "github:blink-new/browser-mcp"]
}
}
}
```
### Cursor / VS Code with MCP Extension
Add to your MCP configuration:
```json
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["-y", "github:blink-new/browser-mcp"]
}
}
}
```
### With Environment Variables
For headless servers or containers:
```json
{
"mcp": {
"browser": {
"type": "local",
"command": ["npx", "-y", "github:blink-new/browser-mcp"],
"environment": {
"BROWSER_MCP_NO_SANDBOX": "true",
"BROWSER_MCP_HEADLESS": "true"
},
"enabled": true
}
}
}
```
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `BROWSER_MCP_HEADLESS` | Run browser in headless mode | `true` |
| `BROWSER_MCP_NO_SANDBOX` | Disable Chrome sandbox (required for Docker/root) | `false` |
| `BROWSER_MCP_EXECUTABLE_PATH` | Path to Chrome/Chromium executable | Auto-detected |
| `BROWSER_MCP_ARGS` | Additional Chrome arguments (comma-separated) | None |
## Available Tools
### Navigation
| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to a URL |
| `browser_back` | Go back to previous page |
| `browser_forward` | Go forward to next page |
| `browser_reload` | Reload current page |
### Screenshots & Content
| Tool | Description |
|------|-------------|
| `browser_screenshot` | Take a screenshot (supports fullPage option) |
| `browser_title` | Get the page title |
| `browser_content` | Get HTML content (optional selector) |
| `browser_links` | Get all links on the page |
### Interaction
| Tool | Description |
|------|-------------|
| `browser_click` | Click on an element by CSS selector |
| `browser_type` | Type text into an input field |
| `browser_hover` | Hover over an element |
| `browser_select` | Select an option from a dropdown |
| `browser_scroll` | Scroll up or down |
### Utilities
| Tool | Description |
|------|-------------|
| `browser_wait` | Wait for time or element |
| `browser_evaluate` | Execute JavaScript |
| `browser_close` | Close the browser |
## Examples
### Navigate and Screenshot
```
User: Go to example.com and take a screenshot
AI: [Uses browser_navigate with url="https://example.com"]
AI: [Uses browser_screenshot]
```
### Fill a Form
```
User: Fill out the contact form on the page
AI: [Uses browser_type with selector="#name" text="John Doe"]
AI: [Uses browser_type with selector="#email" text="john@example.com"]
AI: [Uses browser_click with selector="#submit"]
```
### Extract Data
```
User: Get all the links from this page
AI: [Uses browser_links]
```
## Troubleshooting
### Linux: Browser fails to launch
If you see errors about missing libraries, install the Chromium dependencies:
```bash
sudo apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2
```
### Docker/Root: Sandbox errors
Use the `--no-sandbox` flag:
```bash
BROWSER_MCP_NO_SANDBOX=true npx github:blink-new/browser-mcp
```
Or in your config:
```json
{
"environment": {
"BROWSER_MCP_NO_SANDBOX": "true"
}
}
```
### macOS: Puppeteer can't find Chrome
The bundled Chromium should work automatically. If not, specify the path:
```bash
BROWSER_MCP_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" npx github:blink-new/browser-mcp
```
### Windows: Long path errors
Run PowerShell as Administrator and enable long paths:
```powershell
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
```
## Docker Support
Example Dockerfile:
```dockerfile
FROM node:20-slim
# Install Chromium dependencies
RUN apt-get update && apt-get install -y \
libnss3 \
libatk1.0-0 \
libatk-bridge2.0-0 \
libcups2 \
libdrm2 \
libxkbcommon0 \
libxcomposite1 \
libxdamage1 \
libxfixes3 \
libxrandr2 \
libgbm1 \
libasound2 \
libpango-1.0-0 \
libcairo2 \
&& rm -rf /var/lib/apt/lists/*
ENV BROWSER_MCP_NO_SANDBOX=true
ENV BROWSER_MCP_HEADLESS=true
CMD ["npx", "-y", "github:blink-new/browser-mcp"]
```
## Development
```bash
# Clone the repository
git clone https://github.com/blink-new/browser-mcp.git
cd browser-mcp
# Install dependencies
npm install
# Run in development mode
npm run dev
# Build
npm run build
# Run production build
npm start
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT License - see [LICENSE](LICENSE) for details.
## Credits
- Built with [Puppeteer](https://pptr.dev/)
- Uses [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
