Skip to content

Commit c7edea4

Browse files
michioswmichiosw
committed
fix: updated readme
1 parent 3127cc1 commit c7edea4

File tree

1 file changed

+122
-138
lines changed

1 file changed

+122
-138
lines changed

Diff for: ‎README.md

+122-138
Original file line numberDiff line numberDiff line change
@@ -1,137 +1,68 @@
1-
# ➡️ browser-use mcp server
1+
# browser-use-mcp-server
2+
3+
<div align="center">
24

35
[![Twitter URL](https://img.shields.io/twitter/url/https/twitter.com/cobrowser.svg?style=social&label=Follow%20%40cobrowser)](https://x.com/cobrowser)
46
[![PyPI version](https://badge.fury.io/py/browser-use-mcp-server.svg)](https://pypi.org/project/browser-use-mcp-server/)
57

6-
[browser-use](https://github.com/browser-use/browser-use) MCP Server with SSE +
7-
stdio transport
8-
9-
### Requirements
10-
11-
- [uv](https://github.com/astral-sh/uv)
12-
- [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) (for stdio)
8+
**An MCP server that enables AI agents to control web browsers using [browser-use](https://github.com/browser-use/browser-use).**
139

14-
```
15-
# 1. Install uv
16-
curl -LsSf https://astral.sh/uv/install.sh | sh
17-
# 2. Install mcp-proxy pypi package via uv
18-
uv tool install mcp-proxy
19-
```
10+
</div>
2011

21-
### Quickstart
12+
## Prerequisites
2213

23-
Starting in SSE mode:
14+
- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
15+
- [Playwright](https://playwright.dev/) - Browser automation
16+
- [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) - Required for stdio mode
2417

2518
```bash
26-
uv sync
27-
uv pip install playwright
28-
uv run playwright install --with-deps --no-shell chromium
29-
uv run server --port 8000
30-
```
31-
32-
With stdio mode:
33-
34-
```bash
35-
# Run with stdio mode and specify a proxy port
36-
uv run server --stdio --proxy-port 8001
37-
38-
# Or just stdio mode (random proxy port)
39-
uv run server --stdio
19+
# Install prerequisites
20+
curl -LsSf https://astral.sh/uv/install.sh | sh
21+
uv tool install mcp-proxy
4022
```
4123

42-
- the .env requires the following:
24+
## Environment
4325

26+
Create a `.env` file:
4427
```
45-
OPENAI_API_KEY=[your api key]
46-
CHROME_PATH=[only change this if you have a custom chrome build]
47-
PATIENT=false # Set to true if you want api calls to wait for tasks to complete (default is false)
28+
OPENAI_API_KEY=your-api-key
29+
CHROME_PATH=optional/path/to/chrome
30+
PATIENT=false # Set to true if API calls should wait for task completion
4831
```
4932

50-
When building the docker image, you can use Docker secrets for VNC password:
33+
## Installation
5134

5235
```bash
53-
# With Docker secrets (recommended for production)
54-
echo "your-secure-password" > vnc_password.txt
55-
docker run -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password your-image-name
56-
57-
# Or during development with the default password
58-
docker build .
59-
```
60-
61-
### Local Development and Testing
62-
63-
To develop and test the package locally:
64-
65-
1. Build a distributable wheel:
66-
67-
```bash
68-
# From the project root directory
69-
uv build
36+
# Install dependencies
37+
uv sync
38+
uv pip install playwright
39+
uv run playwright install --with-deps --no-shell chromium
7040
```
7141

72-
2. Install it as a global tool using the built wheel:
42+
## Usage
7343

74-
```bash
75-
uv tool install dist/browser_use_mcp_server-*.whl
76-
```
77-
78-
3. Run the tool from any directory:
44+
### SSE Mode
7945

8046
```bash
81-
# Set your OpenAI API key for the current session
82-
export OPENAI_API_KEY=your-api-key-here
83-
84-
# Or provide it inline for a one-time run
85-
OPENAI_API_KEY=your-api-key-here browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
47+
# Run directly from source
48+
uv run server --port 8000
8649
```
8750

88-
4. After making changes, rebuild and reinstall:
51+
### stdio Mode
8952

9053
```bash
54+
# 1. Build and install globally
9155
uv build
92-
uv tool uninstall browser-use-mcp-server
56+
uv tool uninstall browser-use-mcp-server 2>/dev/null || true
9357
uv tool install dist/browser_use_mcp_server-*.whl
94-
```
95-
96-
### Tools
97-
98-
- [x] SSE transport
99-
- [x] stdio transport (via mcp-proxy)
100-
- [x] browser_use - Initiates browser tasks with URL and action
101-
- [x] browser_get_result - Retrieves results of async browser tasks
102-
- [x] VNC server - stream the dockerized browser to your client
103-
104-
### VNC
105-
106-
the dockerfile has a vnc server with a default password of browser-use. connect
107-
to it:
10858

59+
# 2. Run with stdio transport
60+
browser-use-mcp-server run server --stdio --proxy-port 9000
10961
```
110-
docker build -t browser-use-mcp-server .
111-
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
112-
git clone https://github.com/novnc/noVNC
113-
cd noVNC
114-
./utils/novnc_proxy --vnc localhost:5900
115-
```
116-
117-
<p align="center">
118-
<img width="428" alt="Screenshot 2025-03-24 at 12 03 15 PM" src="https://github.com/user-attachments/assets/45bc5bee-418d-4182-94f5-db84b4fc0b3a" />
119-
<br>
120-
<img width="428" alt="Screenshot 2025-03-24 at 12 11 42 PM" src="https://github.com/user-attachments/assets/7db53f41-fc00-4e48-8892-f7108096f9c4" />
121-
</p>
122-
123-
### Supported Clients
12462

125-
- cursor.ai
126-
- claude desktop
127-
- claude code
128-
- windsurf ([windsurf](https://codeium.com/windsurf) doesn't support SSE, only
129-
stdio)
63+
## Client Configuration
13064

131-
#### SSE Mode
132-
133-
After running the server in SSE mode, add http://localhost:8000/sse to your
134-
client UI, or in a mcp.json file:
65+
### SSE Mode
13566

13667
```json
13768
{
@@ -143,29 +74,14 @@ client UI, or in a mcp.json file:
14374
}
14475
```
14576

146-
#### stdio Mode
147-
148-
When running in stdio mode, the server will automatically start both the SSE
149-
server and mcp-proxy. The proxy handles the conversion between stdio and SSE
150-
protocols. No additional configuration is needed - just start your client and it
151-
will communicate with the server through stdin/stdout.
152-
153-
For Windsurf integration, add this to your config:
77+
### stdio Mode
15478

15579
```json
15680
{
15781
"mcpServers": {
15882
"browser-server": {
15983
"command": "browser-use-mcp-server",
160-
"args": [
161-
"run",
162-
"server",
163-
"--port",
164-
"8000",
165-
"--stdio",
166-
"--proxy-port",
167-
"9000"
168-
],
84+
"args": ["run", "server", "--stdio", "--proxy-port", "9000"],
16985
"env": {
17086
"OPENAI_API_KEY": "your-api-key"
17187
}
@@ -174,35 +90,103 @@ For Windsurf integration, add this to your config:
17490
}
17591
```
17692

177-
### Client Configuration Paths
93+
### Config Locations
17894

179-
#### Cursor
95+
| Client | Configuration Path |
96+
|--------|-------------------|
97+
| Cursor | `./.cursor/mcp.json` |
98+
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
99+
| Claude (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
100+
| Claude (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
180101

181-
- `./.cursor/mcp.json`
102+
## Features
182103

183-
#### Windsurf
104+
- [x] **Browser Automation**: Control browsers through AI agents
105+
- [x] **Dual Transport**: Support for both SSE and stdio protocols
106+
- [x] **VNC Streaming**: Watch browser automation in real-time
107+
- [x] **Async Tasks**: Execute browser operations asynchronously
184108

185-
- `~/.codeium/windsurf/mcp_config.json`
109+
## Local Development
186110

187-
#### Claude
111+
To develop and test the package locally:
188112

189-
- `~/Library/Application Support/Claude/claude_desktop_config.json`
190-
- `%APPDATA%\Claude\claude_desktop_config.json`
113+
1. Build a distributable wheel:
114+
```bash
115+
# From the project root directory
116+
uv build
117+
```
118+
119+
2. Install it as a global tool:
120+
```bash
121+
uv tool uninstall browser-use-mcp-server 2>/dev/null || true
122+
uv tool install dist/browser_use_mcp_server-*.whl
123+
```
124+
125+
3. Run from any directory:
126+
```bash
127+
# Set your OpenAI API key for the current session
128+
export OPENAI_API_KEY=your-api-key-here
129+
130+
# Or provide it inline for a one-time run
131+
OPENAI_API_KEY=your-api-key-here browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
132+
```
191133

192-
### Example Usage
134+
4. After making changes, rebuild and reinstall:
135+
```bash
136+
uv build
137+
uv tool uninstall browser-use-mcp-server
138+
uv tool install dist/browser_use_mcp_server-*.whl
139+
```
193140

194-
Try asking your LLM the following:
141+
## Docker
195142

196-
`open https://news.ycombinator.com and return the top ranked article`
143+
```bash
144+
# Run with default VNC password
145+
docker build -t browser-use-mcp-server .
146+
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
147+
148+
# Use custom VNC password
149+
echo "your-password" > vnc_password.txt
150+
docker run --rm -p8000:8000 -p5900:5900 \
151+
-v $(pwd)/vnc_password.txt:/run/secrets/vnc_password \
152+
browser-use-mcp-server
153+
```
154+
155+
### VNC Viewer
156+
157+
```bash
158+
# Browser-based viewer
159+
git clone https://github.com/novnc/noVNC
160+
cd noVNC
161+
./utils/novnc_proxy --vnc localhost:5900
162+
```
163+
164+
Default password: `browser-use`
165+
166+
<div align="center">
167+
<img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/45bc5bee-418d-4182-94f5-db84b4fc0b3a" />
168+
<br><br>
169+
<img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/7db53f41-fc00-4e48-8892-f7108096f9c4" />
170+
</div>
171+
172+
## Example
173+
174+
Try asking your AI:
175+
176+
```
177+
open https://news.ycombinator.com and return the top ranked article
178+
```
197179

198-
### Help
180+
## Support
199181

200-
for issues or interest reach out @ https://cobrowser.xyz
182+
For issues or inquiries: [cobrowser.xyz](https://cobrowser.xyz)
201183

202-
# Stars
184+
## Star History
203185

204-
<picture>
205-
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date&theme=dark" />
206-
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
207-
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
208-
</picture>
186+
<div align="center">
187+
<picture>
188+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date&theme=dark" />
189+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
190+
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
191+
</picture>
192+
</div>

0 commit comments

Comments
 (0)