Dev

.env.example

@@ -5,4 +5,8 @@ CHROME_PATH=
 OPENAI_API_KEY=your-api-key-here
 
 # Set to true if you want api calls to wait for tasks to complete (default is false)
-PATIENT=false
+PATIENT=false
+
+# Set to true if you want to disable anonymous telemetry (default is false)
+ANONYMIZED_TELEMETRY=false
+

README.md

@@ -1,85 +1,71 @@
-# ➡️ browser-use mcp server
+# browser-use-mcp-server
 
-[browser-use](https://github.com/browser-use/browser-use) MCP Server with SSE
-transport
+<div align="center">
 
-### requirements
+[![Twitter URL](https://img.shields.io/twitter/url/https/twitter.com/cobrowser.svg?style=social&label=Follow%20%40cobrowser)](https://x.com/cobrowser)
+[![PyPI version](https://badge.fury.io/py/browser-use-mcp-server.svg)](https://pypi.org/project/browser-use-mcp-server/)
 
-- uv
+**An MCP server that enables AI agents to control web browsers using
+[browser-use](https://github.com/browser-use/browser-use).**
 
-```
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
+</div>
 
-### quickstart
+## Prerequisites
 
-```
-uv sync
-uv pip install playwright
-uv run playwright install --with-deps --no-shell chromium
-uv run server --port 8000
-```
-
-- the .env requires the following:
+- [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
 
-```
-OPENAI_API_KEY=[your api key]
-CHROME_PATH=[only change this if you have a custom chrome build]
-PATIENT=false # Set to true if you want api calls to wait for tasks to complete (default is false)
+```bash
+# Install prerequisites
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install mcp-proxy
+uv tool update-shell
 ```
 
-- we will be adding support for other LLM providers to power browser-use
-  (claude, grok, bedrock, etc)
+## Environment
 
-when building the docker image, you can use Docker secrets for VNC password:
+Create a `.env` file:
 
 ```
-# With Docker secrets (recommended for production)
-echo "your-secure-password" > vnc_password.txt
-docker run -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password your-image-name
-
-# Or during development with the default password
-docker build .
+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
 ```
 
-### tools
+## Installation
 
-- [x] SSE transport
-- [x] browser_use - Initiates browser tasks with URL and action
-- [x] browser_get_result - Retrieves results of async browser tasks
-- [x] VNC server - stream the dockerized browser to your client
+```bash
+# Install dependencies
+uv sync
+uv pip install playwright
+uv run playwright install --with-deps --no-shell chromium
+```
 
-### VNC
+## Usage
 
-the dockerfile has a vnc server with a default password of browser-use. connect
-to it:
+### SSE Mode
 
-```
-docker build -t  browser-use-mcp-server .
-docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
-git clone https://github.com/novnc/noVNC
-cd noVNC
-./utils/novnc_proxy --vnc localhost:5900
+```bash
+# Run directly from source
+uv run server --port 8000
 ```
 
-<p align="center">
-<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" />
-<br>
-<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" />
-</p>
+### stdio Mode
 
-### supported clients
+```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
 
-- cursor.ai
-- claude desktop
-- claude code
-- <s>windsurf</s> ([windsurf](https://codeium.com/windsurf) doesn't support SSE
-  yet)
+# 2. Run with stdio transport
+browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
+```
 
-### usage
+## Client Configuration
 
-after running the server, add http://localhost:8000/sse to your client UI, or in
-a mcp.json file:
+### SSE Mode
 
 ```json
 {
@@ -91,31 +77,130 @@ a mcp.json file:
 }
 ```
 
-#### cursor
+### stdio Mode
 
-- `./.cursor/mcp.json`
+```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
 
-#### windsurf
+   # 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
+   ```
 
-- `~/.codeium/windsurf/mcp_config.json`
+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
+   ```
 
-#### claude
+## Docker
 
-- `~/Library/Application Support/Claude/claude_desktop_config.json`
-- `%APPDATA%\Claude\claude_desktop_config.json`
+```bash
+# Run with default VNC password
+docker build -t browser-use-mcp-server .
+docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
+
+# Use custom VNC password
+echo "your-password" > vnc_password.txt
+docker run --rm -p8000:8000 -p5900:5900 \
+  -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password \
+  browser-use-mcp-server
+```
+
+### 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`
+
+<div align="center">
+  <img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/45bc5bee-418d-4182-94f5-db84b4fc0b3a" />
+  <br><br>
+  <img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/7db53f41-fc00-4e48-8892-f7108096f9c4" />
+</div>
 
-then try asking your LLM the following:
+## Example
 
-`open https://news.ycombinator.com and return the top ranked article`
+Try asking your AI:
+
+```
+open https://news.ycombinator.com and return the top ranked article
+```
 
-### help
+## Support
 
-for issues or interest reach out @ https://cobrowser.xyz
+For issues or inquiries: [cobrowser.xyz](https://cobrowser.xyz)
 
-# stars
+## Star History
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date&theme=dark" />
-  <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
-  <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
-</picture>
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
+  </picture>
+</div>

pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "pydantic>=2.10.6",
     "anyio",
     "python-dotenv",
+    "python-json-logger>=2.0.7",
     "starlette",
     "uvicorn",
     "playwright>=1.50.0",
@@ -72,4 +73,8 @@ disallow_incomplete_defs = true
 browser-use-mcp-server = "browser_use_mcp_server.cli:cli"
 
 [tool.hatch.build]
-packages = ["src/browser_use_mcp_server"]
+packages = ["src", "server"]
+include = ["server"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/browser_use_mcp_server", "server"]