Browser Use MCP Server

1# browser-use-mcp-server
2 
3<div align="center">
4 
5[![Twitter URL](https://img.shields.io/twitter/url/https/twitter.com/cobrowser.svg?style=social&label=Follow%20%40cobrowser)](https://x.com/cobrowser)
6[![Discord](https://img.shields.io/discord/1351569878116470928?logo=discord&logoColor=white&label=discord&color=white)](https://discord.gg/gw9UpFUhyY)
7[![PyPI version](https://badge.fury.io/py/browser-use-mcp-server.svg)](https://badge.fury.io/py/browser-use-mcp-server)
8 
9**An MCP server that enables AI agents to control web browsers using
10[browser-use](https://github.com/browser-use/browser-use).**
11 
12> **🌐 Want to Vibe Browse the Web?** Open-source AI-powered web browser - [**Vibe Browser**](https://github.com/co-browser/vibe).
13>
14> **🔗 Managing multiple MCP servers?** Simplify your development workflow with [agent-browser](https://github.com/co-browser/agent-browser)
15 
16</div>
17 
18## Prerequisites
19 
20- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
21- [Playwright](https://playwright.dev/) - Browser automation
22- [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) - Required for stdio mode
23 
24```bash
25# Install prerequisites
26curl -LsSf https://astral.sh/uv/install.sh | sh
27uv tool install mcp-proxy
28uv tool update-shell
29```
30 
31## Environment
32 
33Create a `.env` file:
34 
35```bash
36OPENAI_API_KEY=your-api-key
37CHROME_PATH=optional/path/to/chrome
38PATIENT=false  # Set to true if API calls should wait for task completion
39```
40 
41## Installation
42 
43```bash
44# Install dependencies
45uv sync
46uv pip install playwright
47uv run playwright install --with-deps --no-shell chromium
48```
49 
50## Usage
51 
52### SSE Mode
53 
54```bash
55# Run directly from source
56uv run server --port 8000
57```
58 
59### stdio Mode
60 
61```bash
62# 1. Build and install globally
63uv build
64uv tool uninstall browser-use-mcp-server 2>/dev/null || true
65uv tool install dist/browser_use_mcp_server-*.whl
66 
67# 2. Run with stdio transport
68browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
69```
70 
71## Client Configuration
72 
73### SSE Mode Client Configuration
74 
75```json
76{
77  "mcpServers": {
78    "browser-use-mcp-server": {
79      "url": "http://localhost:8000/sse"
80    }
81  }
82}
83```
84 
85### stdio Mode Client Configuration
86 
87```json
88{
89  "mcpServers": {
90    "browser-server": {
91      "command": "browser-use-mcp-server",
92      "args": [
93        "run",
94        "server",
95        "--port",
96        "8000",
97        "--stdio",
98        "--proxy-port",
99        "9000"
100      ],
101      "env": {
102        "OPENAI_API_KEY": "your-api-key"
103      }
104    }
105  }
106}
107```
108 
109### Config Locations
110 
111| Client           | Configuration Path                                                |
112| ---------------- | ----------------------------------------------------------------- |
113| Cursor           | `./.cursor/mcp.json`                                              |
114| Windsurf         | `~/.codeium/windsurf/mcp_config.json`                             |
115| Claude (Mac)     | `~/Library/Application Support/Claude/claude_desktop_config.json` |
116| Claude (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     |
117 
118## Features
119 
120- [x] **Browser Automation**: Control browsers through AI agents
121- [x] **Dual Transport**: Support for both SSE and stdio protocols
122- [x] **VNC Streaming**: Watch browser automation in real-time
123- [x] **Async Tasks**: Execute browser operations asynchronously
124 
125## Local Development
126 
127To develop and test the package locally:
128 
1291. Build a distributable wheel:
130 
131   ```bash
132   # From the project root directory
133   uv build
134   ```
135 
1362. Install it as a global tool:
137 
138   ```bash
139   uv tool uninstall browser-use-mcp-server 2>/dev/null || true
140   uv tool install dist/browser_use_mcp_server-*.whl
141   ```
142 
1433. Run from any directory:
144 
145   ```bash
146   # Set your OpenAI API key for the current session
147   export OPENAI_API_KEY=your-api-key-here
148 
149   # Or provide it inline for a one-time run
150   OPENAI_API_KEY=your-api-key-here browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
151   ```
152 
1534. After making changes, rebuild and reinstall:
154   ```bash
155   uv build
156   uv tool uninstall browser-use-mcp-server
157   uv tool install dist/browser_use_mcp_server-*.whl
158   ```
159 
160## Docker
161 
162Using Docker provides a consistent and isolated environment for running the server.
163 
164```bash
165# Build the Docker image
166docker build -t browser-use-mcp-server .
167 
168# Run the container with the default VNC password ("browser-use")
169# --rm ensures the container is automatically removed when it stops
170# -p 8000:8000 maps the server port
171# -p 5900:5900 maps the VNC port
172docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
173 
174# Run with a custom VNC password read from a file
175# Create a file (e.g., vnc_password.txt) containing only your desired password
176echo "your-secure-password" > vnc_password.txt
177# Mount the password file as a secret inside the container
178docker run --rm -p8000:8000 -p5900:5900 \
179  -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password:ro \
180  browser-use-mcp-server
181```
182 
183*Note: The `:ro` flag in the volume mount (`-v`) makes the password file read-only inside the container for added security.*
184 
185### VNC Viewer
186 
187```bash
188# Browser-based viewer
189git clone https://github.com/novnc/noVNC
190cd noVNC
191./utils/novnc_proxy --vnc localhost:5900
192```
193 
194Default password: `browser-use` (unless overridden using the custom password method)
195 
196<div align="center">
197  <img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/45bc5bee-418d-4182-94f5-db84b4fc0b3a" />
198  <br><br>
199  <img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/7db53f41-fc00-4e48-8892-f7108096f9c4" />
200</div>
201 
202## Example
203 
204Try asking your AI:
205 
206```text
207open https://news.ycombinator.com and return the top ranked article
208```
209 
210## Support
211 
212For issues or inquiries: [cobrowser.xyz](https://cobrowser.xyz)
213 
214## Star History
215 
216<div align="center">
217  <picture>
218    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date&theme=dark" />
219    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
220    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
221  </picture>
222</div>
223