Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

Update MCP server documentation with cloud and local options

ShawnPana1e2dc7e9eae2
diff --git a/docs/customize/integrations/mcp-server.mdx b/docs/customize/integrations/mcp-server.mdx
index 97ef3c78f..cfc7acc28 100644
--- a/docs/customize/integrations/mcp-server.mdx
+++ b/docs/customize/integrations/mcp-server.mdx
@@ -1,37 +1,172 @@
---
title: "Browser Automation MCP"
-description: "Expose browser-use capabilities via Model Context Protocol for AI assistants like Claude Desktop"
+description: "Connect AI assistants to browser-use via Model Context Protocol - cloud or self-hosted"
icon: "server"
mode: "wide"
---
## Overview
-The MCP (Model Context Protocol) Server allows you to expose browser-use's browser automation capabilities to AI assistants like Claude Desktop, Cline, and other MCP-compatible clients. This enables AI assistants to perform web automation tasks directly through browser-use.
+Browser-use provides two ways to expose browser automation capabilities to AI assistants via the Model Context Protocol (MCP):
-## Quick Start
+1. **Cloud MCP Server** (recommended) - Hosted service with simple setup and managed infrastructure
+2. **Local Self-Hosted MCP** - Free, open-source option running on your machine
-### Start MCP Server
+Both enable AI assistants like Claude Desktop, Claude Code, and other MCP-compatible clients to perform web automation tasks.
+
+## Cloud MCP Server (Recommended)
+
+Browser Use provides a hosted **Model Context Protocol (MCP)** server that enables AI assistants to control browser automation. Works with any HTTP-based MCP client.
+
+**MCP Server URL:** `https://api.browser-use.com/mcp`
+
+This is an **HTTP-based MCP server** designed for cloud integrations and remote access with managed infrastructure, persistent authentication profiles, and simplified setup.
+
+### Quick Setup
+
+#### 1. Get API Key
+Get your API key from the [Browser Use Dashboard](https://cloud.browser-use.com)
+
+#### 2. Connect Your AI
+
+<Tabs>
+<Tab title="Claude Code">
+```bash
+claude mcp add --transport http browser-use https://api.browser-use.com/mcp
+```
+</Tab>
+<Tab title="Claude Desktop">
+Add to your Claude Desktop config file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+ "mcpServers": {
+ "browser-use": {
+ "url": "https://api.browser-use.com/mcp",
+ "headers": {
+ "X-Browser-Use-API-Key": "Your-API-Key-Here"
+ }
+ }
+ }
+}
+```
+
+Restart Claude Desktop after saving.
+</Tab>
+<Tab title="Cursor">
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+ "mcpServers": {
+ "browser-use": {
+ "url": "https://api.browser-use.com/mcp",
+ "headers": {
+ "X-Browser-Use-API-Key": "Your-API-Key-Here"
+ }
+ }
+ }
+}
+```
+</Tab>
+<Tab title="Windsurf">
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+ "mcpServers": {
+ "browser-use": {
+ "serverUrl": "https://api.browser-use.com/mcp",
+ "headers": {
+ "X-Browser-Use-API-Key": "Your-API-Key-Here"
+ }
+ }
+ }
+}
+```
+</Tab>
+</Tabs>
+
+### Available Tools
+
+The cloud MCP server provides three high-level tools:
+
+#### `browser_task`
+Creates and runs a browser automation task.
+- **task** (required): What you want the browser to do
+- **max_steps** (optional): Max actions to take (1-10, default: 8)
+- **use_profile** (optional): Use a cloud profile for persistent authentication (default: false)
+- **profile_id** (optional): UUID of the profile to use (required when use_profile=true)
+
+#### `list_browser_profiles`
+Lists all available cloud browser profiles for the authenticated project. Profiles store persistent authentication (cookies, sessions) for websites requiring login.
+
+#### `monitor_task`
+Checks the current status and progress of a browser automation task. Returns immediately with a snapshot of the task state.
+- **session_id** (required): UUID of the session to monitor (returned by browser_task)
+
+### Example Usage
+
+Once connected, ask your AI to perform web tasks:
+
+> "Search Google for the latest iPhone reviews and summarize the top 3 results"
+
+> "Go to Hacker News and get me the titles of the top 5 posts"
+
+> "Fill out the contact form on example.com with my information"
+
+The AI will use the browser tools automatically to complete these tasks.
+
+### Smart Features
+
+**Cloud Profiles for Authentication**
+Use cloud browser profiles to maintain persistent login sessions across tasks. Profiles store cookies and authentication state for:
+- Social media (X/Twitter, LinkedIn, Facebook)
+- Email (Gmail, Outlook)
+- Online banking and shopping sites
+- Any website requiring login
+
+List available profiles with `list_browser_profiles`, then pass the `profile_id` to `browser_task`.
+
+**Real-time Task Monitoring**
+Use `monitor_task` to check task progress while it's running. The tool returns immediately with the current status, latest step details, and agent reasoning. Call it repeatedly to track progress live.
+
+**Conversational Progress Summaries**
+When you monitor tasks, the AI automatically interprets step data into natural language updates, explaining what the browser has completed and what it's currently working on.
+
+---
+
+## Local Self-Hosted Alternative
+
+For users who want a free, self-hosted option, browser-use can run as a local MCP server on your machine. This requires your own OpenAI or Anthropic API keys but provides direct, low-level control over browser automation.
+
+### Quick Start
+
+The local MCP server runs as a stdio-based process on your machine. This is the **free, open-source option** but requires your own LLM API keys.
+
+#### Start MCP Server Manually
```bash
-uvx browser-use --mcp
+uvx --from 'browser-use[cli]' browser-use --mcp
```
The server will start in stdio mode, ready to accept MCP connections.
-## Claude Desktop Integration
+#### Claude Desktop Integration
The most common use case is integrating with Claude Desktop. Add this configuration to your Claude Desktop config file:
-### macOS
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"browser-use": {
- "command": "uvx",
- "args": ["browser-use", "--mcp"],
+ "command": "/Users/your-username/.local/bin/uvx",
+ "args": ["--from", "browser-use[cli]", "browser-use", "--mcp"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key-here"
}
@@ -40,15 +175,14 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
}
```
-### Windows
-Edit `%APPDATA%\Claude\claude_desktop_config.json`:
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"browser-use": {
"command": "uvx",
- "args": ["browser-use", "--mcp"],
+ "args": ["--from", "browser-use[cli]", "browser-use", "--mcp"],
"env": {
"OPENAI_API_KEY": "your-openai-api-key-here"
}
@@ -57,7 +191,16 @@ Edit `%APPDATA%\Claude\claude_desktop_config.json`:
}
```
-### Environment Variables
+<Note>
+**macOS/Linux PATH Issue:** Claude Desktop may not find `uvx` in your PATH. Use the full path to `uvx` instead:
+- Run `which uvx` in your terminal to find the location (usually `/Users/username/.local/bin/uvx` or `~/.local/bin/uvx`)
+- Replace `"command": "uvx"` with the full path, e.g., `"command": "/Users/your-username/.local/bin/uvx"`
+- Replace `your-username` with your actual username
+
+**CLI Extras Required:** The `--from browser-use[cli]` flag installs the CLI extras needed for MCP server support.
+</Note>
+
+#### Environment Variables
You can configure browser-use through environment variables:
@@ -66,14 +209,14 @@ You can configure browser-use through environment variables:
- `BROWSER_USE_HEADLESS` - Set to `false` to show browser window
- `BROWSER_USE_DISABLE_SECURITY` - Set to `true` to disable browser security features
-## Available Tools
+### Available Tools
-The MCP server exposes these browser automation tools:
+The local MCP server exposes these low-level browser automation tools for direct control:
-### Autonomous Agent Tools
+#### Autonomous Agent Tools
- **`retry_with_browser_use_agent`** - Run a complete browser automation task with an AI agent (use as last resort when direct control fails)
-### Direct Browser Control
+#### Direct Browser Control
- **`browser_navigate`** - Navigate to a URL
- **`browser_click`** - Click on an element by index
- **`browser_type`** - Type text into an element
@@ -81,20 +224,20 @@ The MCP server exposes these browser automation tools:
- **`browser_scroll`** - Scroll the page
- **`browser_go_back`** - Go back in browser history
-### Tab Management
+#### Tab Management
- **`browser_list_tabs`** - List all open browser tabs
- **`browser_switch_tab`** - Switch to a specific tab
- **`browser_close_tab`** - Close a tab
-### Content Extraction
+#### Content Extraction
- **`browser_extract_content`** - Extract structured content from the current page
-### Session Management
+#### Session Management
- **`browser_list_sessions`** - List all active browser sessions with details
- **`browser_close_session`** - Close a specific browser session by ID
- **`browser_close_all`** - Close all active browser sessions
-## Example Usage
+### Example Usage
Once configured with Claude Desktop, you can ask Claude to perform browser automation tasks:
@@ -108,7 +251,7 @@ Once configured with Claude Desktop, you can ask Claude to perform browser autom
Claude will use the MCP server to execute these tasks through browser-use.
-## Programmatic Usage
+### Programmatic Usage
You can also connect to the MCP server programmatically:
@@ -120,24 +263,24 @@ from mcp.client.stdio import stdio_client
async def use_browser_mcp():
# Connect to browser-use MCP server
server_params = StdioServerParameters(
- command="uvx",
- args=["browser-use", "--mcp"]
+ command="uvx",
+ args=["--from", "browser-use[cli]", "browser-use", "--mcp"]
)
-
+
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
-
+
# Navigate to a website
result = await session.call_tool(
- "browser_navigate",
+ "browser_navigate",
arguments={"url": "https://example.com"}
)
print(result.content[0].text)
-
+
# Get page state
result = await session.call_tool(
- "browser_get_state",
+ "browser_get_state",
arguments={"include_screenshot": True}
)
print("Page state retrieved!")
@@ -145,15 +288,21 @@ async def use_browser_mcp():
asyncio.run(use_browser_mcp())
```
-## Troubleshooting
+### Troubleshooting
-### Common Issues
+#### Common Issues
-**"MCP SDK is required" Error**
+**"CLI addon is not installed" Error**
+Make sure you're using `--from 'browser-use[cli]'` in your uvx command:
```bash
-uv pip install 'browser-use'
+uvx --from 'browser-use[cli]' browser-use --mcp
```
+**"spawn uvx ENOENT" Error (macOS/Linux)**
+Claude Desktop can't find `uvx` in its PATH. Use the full path in your config:
+- Run `which uvx` in terminal to find the location
+- Update your config to use the full path (e.g., `/Users/your-username/.local/bin/uvx`)
+
**Browser doesn't start**
- Check that you have Chrome/Chromium installed
- Try setting `BROWSER_USE_HEADLESS=false` to see browser window
@@ -168,23 +317,24 @@ uv pip install 'browser-use'
- Restart Claude Desktop after config changes
- Check the config file syntax is valid JSON
- Verify the file path is correct for your OS
+- Check logs at `~/Library/Logs/Claude/` (macOS) or `%APPDATA%\Claude\Logs\` (Windows)
-### Debug Mode
+#### Debug Mode
Enable debug logging by setting:
```bash
export BROWSER_USE_LOG_LEVEL=DEBUG
-uvx browser-use --mcp
+uvx --from 'browser-use[cli]' browser-use --mcp
```
-## Security Considerations
+### Security Considerations
- The MCP server has access to your browser and file system
- Only connect trusted MCP clients
- Be cautious with sensitive websites and data
- Consider running in a sandboxed environment for untrusted automation
-## Next Steps
+### Next Steps
- Explore the [examples directory](https://github.com/browser-use/browser-use/tree/main/examples/mcp) for more usage patterns
- Check out [MCP documentation](https://modelcontextprotocol.io/) to learn more about the protocol