Skip to content

Commit 52bfa52

Browse files
michioswhashkode
michiosw
authored and
hashkode
committed
Merge pull request #29 from co-browser/fix/Logging
Fix/logging
2 parents 26f8318 + 9fb3d2d commit 52bfa52

File tree

6 files changed

+231
-118
lines changed

6 files changed

+231
-118
lines changed

Diff for: ‎.env.example

+4-1
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,7 @@ CHROME_PATH=
55
OPENAI_API_KEY=your-api-key-here
66

77
# Set to true if you want api calls to wait for tasks to complete (default is false)
8-
PATIENT=false
8+
PATIENT=false
9+
10+
# Set to true if you want to disable anonymous telemetry (default is false)
11+
ANONYMIZED_TELEMETRY=false

Diff for: ‎README.md

+134-104
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,71 @@
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+
**An MCP server that enables AI agents to control web browsers using
9+
[browser-use](https://github.com/browser-use/browser-use).**
810

9-
### Requirements
11+
</div>
1012

11-
- [uv](https://github.com/astral-sh/uv)
12-
- [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) (for stdio)
13+
## Prerequisites
1314

14-
```
15-
# 1. Install uv
15+
- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
16+
- [Playwright](https://playwright.dev/) - Browser automation
17+
- [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) - Required for stdio mode
18+
19+
```bash
20+
# Install prerequisites
1621
curl -LsSf https://astral.sh/uv/install.sh | sh
17-
# 2. Install mcp-proxy pypi package via uv
1822
uv tool install mcp-proxy
23+
uv tool update-shell
1924
```
2025

21-
### Quickstart
26+
## Environment
2227

23-
Starting in SSE mode:
28+
Create a `.env` file:
2429

25-
```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+
OPENAI_API_KEY=your-api-key
32+
CHROME_PATH=optional/path/to/chrome
33+
PATIENT=false # Set to true if API calls should wait for task completion
3034
```
3135

32-
With stdio mode:
36+
## Installation
3337

3438
```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
39+
# Install dependencies
40+
uv sync
41+
uv pip install playwright
42+
uv run playwright install --with-deps --no-shell chromium
4043
```
4144

42-
- the .env requires the following:
43-
44-
```
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)
48-
```
45+
## Usage
4946

50-
When building the docker image, you can use Docker secrets for VNC password:
47+
### SSE Mode
5148

5249
```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 .
50+
# Run directly from source
51+
uv run server --port 8000
5952
```
6053

61-
### Tools
54+
### stdio Mode
6255

63-
- [x] SSE transport
64-
- [x] stdio transport (via mcp-proxy)
65-
- [x] browser_use - Initiates browser tasks with URL and action
66-
- [x] browser_get_result - Retrieves results of async browser tasks
67-
- [x] VNC server - stream the dockerized browser to your client
68-
69-
### VNC
70-
71-
the dockerfile has a vnc server with a default password of browser-use. connect
72-
to it:
56+
```bash
57+
# 1. Build and install globally
58+
uv build
59+
uv tool uninstall browser-use-mcp-server 2>/dev/null || true
60+
uv tool install dist/browser_use_mcp_server-*.whl
7361

62+
# 2. Run with stdio transport
63+
browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
7464
```
75-
docker build -t browser-use-mcp-server .
76-
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
77-
git clone https://github.com/novnc/noVNC
78-
cd noVNC
79-
./utils/novnc_proxy --vnc localhost:5900
80-
```
81-
82-
<p align="center">
83-
<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" />
84-
<br>
85-
<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" />
86-
</p>
87-
88-
### Supported Clients
89-
90-
- cursor.ai
91-
- claude desktop
92-
- claude code
93-
- windsurf ([windsurf](https://codeium.com/windsurf) doesn't support SSE, only
94-
stdio)
9565

96-
#### SSE Mode
66+
## Client Configuration
9767

98-
After running the server in SSE mode, add http://localhost:8000/sse to your
99-
client UI, or in a mcp.json file:
68+
### SSE Mode
10069

10170
```json
10271
{
@@ -108,20 +77,7 @@ client UI, or in a mcp.json file:
10877
}
10978
```
11079

111-
#### stdio Mode
112-
113-
When running in stdio mode, the server will automatically start both the SSE
114-
server and mcp-proxy. The proxy handles the conversion between stdio and SSE
115-
protocols. No additional configuration is needed - just start your client and it
116-
will communicate with the server through stdin/stdout.
117-
118-
Install the cli
119-
120-
```bash
121-
uv pip install -e .
122-
```
123-
124-
And then e.g., in Windsurf, paste:
80+
### stdio Mode
12581

12682
```json
12783
{
@@ -136,41 +92,115 @@ And then e.g., in Windsurf, paste:
13692
"--stdio",
13793
"--proxy-port",
13894
"9000"
139-
]
95+
],
96+
"env": {
97+
"OPENAI_API_KEY": "your-api-key"
98+
}
14099
}
141100
}
142101
}
143102
```
144103

145-
### Client Configuration Paths
104+
### Config Locations
105+
106+
| Client | Configuration Path |
107+
| ---------------- | ----------------------------------------------------------------- |
108+
| Cursor | `./.cursor/mcp.json` |
109+
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
110+
| Claude (Mac) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
111+
| Claude (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
112+
113+
## Features
114+
115+
- [x] **Browser Automation**: Control browsers through AI agents
116+
- [x] **Dual Transport**: Support for both SSE and stdio protocols
117+
- [x] **VNC Streaming**: Watch browser automation in real-time
118+
- [x] **Async Tasks**: Execute browser operations asynchronously
119+
120+
## Local Development
121+
122+
To develop and test the package locally:
123+
124+
1. Build a distributable wheel:
125+
126+
```bash
127+
# From the project root directory
128+
uv build
129+
```
130+
131+
2. Install it as a global tool:
132+
133+
```bash
134+
uv tool uninstall browser-use-mcp-server 2>/dev/null || true
135+
uv tool install dist/browser_use_mcp_server-*.whl
136+
```
146137

147-
#### Cursor
138+
3. Run from any directory:
148139

149-
- `./.cursor/mcp.json`
140+
```bash
141+
# Set your OpenAI API key for the current session
142+
export OPENAI_API_KEY=your-api-key-here
150143

151-
#### Windsurf
144+
# Or provide it inline for a one-time run
145+
OPENAI_API_KEY=your-api-key-here browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
146+
```
152147

153-
- `~/.codeium/windsurf/mcp_config.json`
148+
4. After making changes, rebuild and reinstall:
149+
```bash
150+
uv build
151+
uv tool uninstall browser-use-mcp-server
152+
uv tool install dist/browser_use_mcp_server-*.whl
153+
```
154154

155-
#### Claude
155+
## Docker
156156

157-
- `~/Library/Application Support/Claude/claude_desktop_config.json`
158-
- `%APPDATA%\Claude\claude_desktop_config.json`
157+
```bash
158+
# Run with default VNC password
159+
docker build -t browser-use-mcp-server .
160+
docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
159161

160-
### Example Usage
162+
# Use custom VNC password
163+
echo "your-password" > vnc_password.txt
164+
docker run --rm -p8000:8000 -p5900:5900 \
165+
-v $(pwd)/vnc_password.txt:/run/secrets/vnc_password \
166+
browser-use-mcp-server
167+
```
161168

162-
Try asking your LLM the following:
169+
### VNC Viewer
163170

164-
`open https://news.ycombinator.com and return the top ranked article`
171+
```bash
172+
# Browser-based viewer
173+
git clone https://github.com/novnc/noVNC
174+
cd noVNC
175+
./utils/novnc_proxy --vnc localhost:5900
176+
```
177+
178+
Default password: `browser-use`
179+
180+
<div align="center">
181+
<img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/45bc5bee-418d-4182-94f5-db84b4fc0b3a" />
182+
<br><br>
183+
<img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/7db53f41-fc00-4e48-8892-f7108096f9c4" />
184+
</div>
185+
186+
## Example
187+
188+
Try asking your AI:
189+
190+
```
191+
open https://news.ycombinator.com and return the top ranked article
192+
```
165193

166-
### Help
194+
## Support
167195

168-
for issues or interest reach out @ https://cobrowser.xyz
196+
For issues or inquiries: [cobrowser.xyz](https://cobrowser.xyz)
169197

170-
# Stars
198+
## Star History
171199

172-
<picture>
173-
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date&theme=dark" />
174-
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
175-
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
176-
</picture>
200+
<div align="center">
201+
<picture>
202+
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date&theme=dark" />
203+
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
204+
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
205+
</picture>
206+
</div>

Diff for: ‎pyproject.toml

+4-2
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ dependencies = [
2525
"pydantic>=2.10.6",
2626
"anyio",
2727
"python-dotenv",
28+
"python-json-logger>=2.0.7",
2829
"starlette",
2930
"uvicorn",
3031
"playwright>=1.50.0",
@@ -72,7 +73,8 @@ disallow_incomplete_defs = true
7273
browser-use-mcp-server = "browser_use_mcp_server.cli:cli"
7374

7475
[tool.hatch.build]
75-
packages = ["src/browser_use_mcp_server"]
76+
packages = ["src", "server"]
77+
include = ["server"]
7678

7779
[tool.hatch.build.targets.wheel]
78-
packages = ["src/browser_use_mcp_server"]
80+
packages = ["src/browser_use_mcp_server", "server"]

0 commit comments

Comments
 (0)