https://github.com/co-browser/browser-use-mcp-server
Browse the web, directly from Cursor etc.
https://github.com/co-browser/browser-use-mcp-server
browser browser-use cursor mcp mcp-server playwright
Last synced: 6 days ago
JSON representation
Browse the web, directly from Cursor etc.
- Host: GitHub
- URL: https://github.com/co-browser/browser-use-mcp-server
- Owner: co-browser
- License: mit
- Created: 2025-03-06T09:47:03.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-04-09T21:10:34.000Z (6 days ago)
- Last Synced: 2025-04-09T21:12:55.653Z (6 days ago)
- Topics: browser, browser-use, cursor, mcp, mcp-server, playwright
- Language: Python
- Homepage:
- Size: 217 KB
- Stars: 205
- Watchers: 4
- Forks: 21
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-mcp-list - @co-browser/browser-use-mcp-server - browser/browser-use-mcp-server?style=social)](https://github.com/co-browser/browser-use-mcp-server): Packages `browser-use` as an MCP server, with Docker support for Chromium and VNC. (Uncategorized / Uncategorized)
- awesome-mcp-servers - @co-browser/browser-use-mcp-server - browser-use packaged as an MCP server with SSE transport. includes a dockerfile to run chromium in docker + a vnc server. (Legend / 📂 <a name="browser-automation"></a>Browser Automation)
- awesome-mcp-servers - @co-browser/browser-use-mcp-server - browser-use packaged as an MCP server with SSE transport. includes a dockerfile to run chromium in docker + a vnc server. (Legend / 📂 <a name="browser-automation"></a>Browser Automation)
- awesome-mcp-servers - Browser-Use MCP Server - Browse the web, directly from Cursor etc. (Table of Contents / Browser Automation)
- awesome-mcp-servers - Browser-Use MCP Server - Browse the web, directly from Cursor etc. (Table of Contents / Browser Automation)
README
# browser-use-mcp-server
[](https://x.com/cobrowser)
[](https://pypi.org/project/browser-use-mcp-server/)
**An MCP server that enables AI agents to control web browsers using
[browser-use](https://github.com/browser-use/browser-use).**
## Prerequisites
- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
- [Playwright](https://playwright.dev/) - Browser automation
- [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) - Required for stdio mode
```bash
# Install prerequisites
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install mcp-proxy
uv tool update-shell
```
## Environment
Create a `.env` file:
```bash
OPENAI_API_KEY=your-api-key
CHROME_PATH=optional/path/to/chrome
PATIENT=false # Set to true if API calls should wait for task completion
```
## Installation
```bash
# Install dependencies
uv sync
uv pip install playwright
uv run playwright install --with-deps --no-shell chromium
```
## Usage
### SSE Mode
```bash
# Run directly from source
uv run server --port 8000
```
### stdio Mode
```bash
# 1. Build and install globally
uv build
uv tool uninstall browser-use-mcp-server 2>/dev/null || true
uv tool install dist/browser_use_mcp_server-*.whl
# 2. Run with stdio transport
browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
```
## Client Configuration
### SSE Mode Client Configuration
```json
{
"mcpServers": {
"browser-use-mcp-server": {
"url": "http://localhost:8000/sse"
}
}
}
```
### stdio Mode Client Configuration
```json
{
"mcpServers": {
"browser-server": {
"command": "browser-use-mcp-server",
"args": [
"run",
"server",
"--port",
"8000",
"--stdio",
"--proxy-port",
"9000"
],
"env": {
"OPENAI_API_KEY": "your-api-key"
}
}
}
}
```
### Config Locations
| Client | Configuration Path |
| ---------------- | ----------------------------------------------------------------- |
| Cursor | `./.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Claude (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
## Features
- [x] **Browser Automation**: Control browsers through AI agents
- [x] **Dual Transport**: Support for both SSE and stdio protocols
- [x] **VNC Streaming**: Watch browser automation in real-time
- [x] **Async Tasks**: Execute browser operations asynchronously
## Local Development
To develop and test the package locally:
1. Build a distributable wheel:
```bash
# From the project root directory
uv build
```
2. Install it as a global tool:
```bash
uv tool uninstall browser-use-mcp-server 2>/dev/null || true
uv tool install dist/browser_use_mcp_server-*.whl
```
3. Run from any directory:
```bash
# Set your OpenAI API key for the current session
export OPENAI_API_KEY=your-api-key-here
# Or provide it inline for a one-time run
OPENAI_API_KEY=your-api-key-here browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
```
4. After making changes, rebuild and reinstall:
```bash
uv build
uv tool uninstall browser-use-mcp-server
uv tool install dist/browser_use_mcp_server-*.whl
```
## Docker
Using Docker provides a consistent and isolated environment for running the server.
```bash
# Build the Docker image
docker build -t browser-use-mcp-server .
# Run the container with the default VNC password ("browser-use")
# --rm ensures the container is automatically removed when it stops
# -p 8000:8000 maps the server port
# -p 5900:5900 maps the VNC port
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
# Run with a custom VNC password read from a file
# Create a file (e.g., vnc_password.txt) containing only your desired password
echo "your-secure-password" > vnc_password.txt
# Mount the password file as a secret inside the container
docker run --rm -p8000:8000 -p5900:5900 \
-v $(pwd)/vnc_password.txt:/run/secrets/vnc_password:ro \
browser-use-mcp-server
```
*Note: The `:ro` flag in the volume mount (`-v`) makes the password file read-only inside the container for added security.*
### VNC Viewer
```bash
# Browser-based viewer
git clone https://github.com/novnc/noVNC
cd noVNC
./utils/novnc_proxy --vnc localhost:5900
```
Default password: `browser-use` (unless overridden using the custom password method)
## Example
Try asking your AI:
```text
open https://news.ycombinator.com and return the top ranked article
```
## Support
For issues or inquiries: [cobrowser.xyz](https://cobrowser.xyz)
## Star History
