Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.
Python ai-agentsai-toolsbrowser-agentbrowser-automationbrowser-usecdpcloud-browsercomputer-useheadless-browserllmmcpplaywrightpythonremote-browserstealth-browserweb-automationweb-scraping
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.mdxindex 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 IntegrationThe 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 VariablesYou 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 UsageOnce 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 automClaude will use the MCP server to execute these tasks through browser-use.-## Programmatic Usage+### Programmatic UsageYou can also connect to the MCP server programmatically:@@ -120,24 +263,24 @@ from mcp.client.stdio import stdio_clientasync def use_browser_mcp():# Connect to browser-use MCP serverserver_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 websiteresult = await session.call_tool(- "browser_navigate",+ "browser_navigate",arguments={"url": "https://example.com"})print(result.content[0].text)-+# Get page stateresult = 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 ModeEnable debug logging by setting:```bashexport 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