MCP Server - Browser Use

The MCP server exposes browser-use’s browser automation capabilities as tools that can be used by AI assistants like Claude Desktop. This allows external MCP clients to control browsers, navigate websites, extract content, and perform automated tasks.

This is the opposite of the MCP Client. The MCP client lets browser-use connect to external MCP servers, while this MCP server lets external AI assistants connect to browser-use.

Overview

The MCP server acts as a bridge between MCP-compatible AI assistants and browser-use:

Installation

uv pip install "browser-use[cli]"

Quick Start

1. Configure Claude Desktop

Add browser-use to your Claude Desktop configuration:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "browser-use": {
      "command": "uvx",
      "args": ["browser-use[cli]", "--mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-..."  // Optional: for content extraction
      }
    }
  }
}

2. Restart Claude Desktop

The browser-use tools will appear in Claude’s tools menu (🔌 icon).

3. Use Browser Automation

Ask Claude to perform browser tasks:

“Navigate to example.com and describe what you see”
“Search for ‘browser automation’ on Google”
“Fill out the contact form on this website”

API Reference

Available Tools

The MCP server exposes the following tools to MCP clients:

`browser_navigate`

Navigate to a URL.

browser_navigate(url: string, new_tab?: boolean): string

Parameters:

Parameter	Type	Required	Description
`url`	`string`	Yes	URL to navigate to
`new_tab`	`boolean`	No	Open in new tab (default: false)

Returns: Success message with URL

`browser_go_back`

Navigate back in browser history.

browser_go_back(): string

Returns: “Navigated back”

Interaction Tools

`browser_click`

Click an element by index.

browser_click(index: number, new_tab?: boolean): string

Parameters:

Parameter	Type	Required	Description
`index`	`number`	Yes	Element index from browser state
`new_tab`	`boolean`	No	Open link in new tab (default: false)

Returns: Success message indicating click action Note: When new_tab is true:

For links: Extracts href and opens in new tab
For other elements: Uses Cmd/Ctrl+Click

`browser_type`

Type text into an input field.

browser_type(index: number, text: string): string

Parameters:

Parameter	Type	Required	Description
`index`	`number`	Yes	Element index from browser state
`text`	`string`	Yes	Text to type

Returns: Success message with typed text

`browser_scroll`

Scroll the page.

browser_scroll(direction?: "up" | "down"): string

Parameters:

Parameter	Type	Required	Description
`direction`	`"up" \| "down"`	No	Scroll direction (default: “down”)

Returns: “Scrolled “

State & Content Tools

`browser_get_state`

Get current browser state with all interactive elements.

browser_get_state(include_screenshot?: boolean): string

Parameters:

Parameter	Type	Required	Description
`include_screenshot`	`boolean`	No	Include base64 screenshot (default: false)

Returns: JSON string containing:

{
  "url": "current page URL",
  "title": "page title",
  "tabs": [{"url": "...", "title": "..."}],
  "interactive_elements": [
    {
      "index": 0,
      "tag": "button",
      "text": "element text (max 100 chars)",
      "placeholder": "if present",
      "href": "if link"
    }
  ],
  "screenshot": "base64 if requested"
}

The interactive elements include all clickable and interactive elements on the page, with their:

index: Used to reference the element in other commands (click, type)
tag: HTML tag name (button, input, a, etc.)
text: Visible text content, truncated to 100 characters
placeholder: For input fields (if present)
href: For links (if present)

`browser_extract_content`

Extract structured content from the current page using AI.

browser_extract_content(query: string, extract_links?: boolean): string

Parameters:

Parameter	Type	Required	Description
`query`	`string`	Yes	What to extract (e.g., “all product prices”)
`extract_links`	`boolean`	No	Include links in extraction (default: false)

Returns: Extracted content based on query Note: Requires OPENAI_API_KEY environment variable for AI extraction.

Tab Management Tools

`browser_list_tabs`

List all open browser tabs.

browser_list_tabs(): string

Returns: JSON array of tab information:

[
  {
    "index": 0,
    "url": "https://example.com",
    "title": "Page Title"
  }
]

`browser_switch_tab`

Switch to a specific tab.

browser_switch_tab(tab_index: number): string

Parameters:

Parameter	Type	Required	Description
`tab_index`	`number`	Yes	Index of tab to switch to

Returns: Success message with tab URL

`browser_close_tab`

Close a specific tab.

browser_close_tab(tab_index: number): string

Parameters:

Parameter	Type	Required	Description
`tab_index`	`number`	Yes	Tab to close

Returns: Success message with closed tab URL

Tool Response Format

All tools return text content. Errors are returned as strings starting with “Error:”.

Configuration

Environment Variables

Configure the MCP server behavior through environment variables in Claude Desktop config:

{
  "mcpServers": {
    "browser-use": {
      "command": "python",
      "args": ["-m", "browser_use.mcp.server"],
      "env": {
        "OPENAI_API_KEY": "sk-..."  // For AI content extraction
      }
    }
  }
}

Browser Profile Settings

The MCP server creates a browser session with these default settings:

Downloads Path: ~/Downloads/browser-use-mcp/
Wait Between Actions: 0.5 seconds
Keep Alive: True (browser stays open between commands)
Allowed Domains: None by default (all domains allowed)

Advanced Usage

Running Standalone

Test the MCP server without Claude Desktop:

# Run server (reads from stdin, writes to stdout)
uvx 'browser-use[cli]' --mcp

# The server communicates via JSON-RPC on stdio

Security Considerations

The MCP server provides full browser control to connected AI assistants. Consider these security measures:

Domain Restrictions: Currently not configurable via environment variables, but the server creates sessions with no domain restrictions by default
File System Access: The server creates a FileSystem instance at ~/.browser-use-mcp for extraction operations
Downloads: Files download to ~/Downloads/browser-use-mcp/

Implementation Details

Browser Session Management

Lazy Initialization: Browser session is created on first browser tool use
Persistent Session: Session remains active across multiple tool calls
Single Session: Currently maintains one browser session per server instance

Tool Categories

Direct Browser Control: Tools starting with browser_ that directly interact with the browser
Agent Tasks: Currently commented out in implementation (browser_use_run_task)

Error Handling

All exceptions are caught and returned as text: "Error: {message}"
Browser session initialization errors are returned to the client
Missing dependencies (e.g., OPENAI_API_KEY) return descriptive error messages

Troubleshooting

Server Not Appearing in Claude

Check configuration path:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Verify Python installation:

uvx 'browser-use[cli]' --version
uvx 'browser-use[cli]' --mcp --help

Check Claude logs:
- macOS: ~/Library/Logs/Claude/mcp.log
- Windows: %APPDATA%\Claude\logs\mcp.log

Browser Not Launching

# Install Playwright browsers
playwright install chromium

# Test browser launch
python -c "from browser_use import BrowserSession; import asyncio; asyncio.run(BrowserSession().start())"

Connection Errors

If you see “MCP server connection failed”:

Test the server directly:
```
uvx 'browser-use[cli]' --mcp
```
Check all dependencies:
```
uv pip install "browser-use[cli]"
```

Content Extraction Not Working

If browser_extract_content returns errors:

Ensure OPENAI_API_KEY is set in the environment configuration
Verify the API key is valid
Check that you have credits/access to the OpenAI API

Limitations

Limitation	Description	Workaround
Single Browser Session	One browser instance per server	Restart server for new session
No Domain Restrictions Config	Cannot configure allowed domains via env vars	Modify server code if needed
No Agent Mode	`browser_use_run_task` is commented out	Use direct browser control tools
Text-Only Responses	All responses are text strings	Parse JSON responses client-side

Comparison with MCP Client

Feature	MCP Server (this)	MCP Client
Purpose	Expose browser to AI	Connect agent to tools
User	Claude Desktop, etc.	Browser-use agents
Direction	External → Browser	Agent → External
Configuration	JSON config file	Python code
Tools	Fixed browser tools	Dynamic from server
Use Case	Interactive assistance	Automated workflows

Code Examples

Simple MCP client example - Basic MCP client connecting to browser-use server
Advanced MCP client example - Multi-server orchestration and complex workflows

Get Started

Customize

Development

​Overview

​Installation

​Quick Start

​1. Configure Claude Desktop

​2. Restart Claude Desktop

​3. Use Browser Automation

​API Reference

​Available Tools

​Navigation Tools

browser_navigate

browser_go_back

​Interaction Tools

browser_click

browser_type

browser_scroll

​State & Content Tools

browser_get_state

browser_extract_content

​Tab Management Tools

browser_list_tabs

browser_switch_tab

browser_close_tab

​Tool Response Format

​Configuration

​Environment Variables

​Browser Profile Settings

​Advanced Usage

​Running Standalone

​Security Considerations

​Implementation Details

​Browser Session Management

​Tool Categories

​Error Handling

​Troubleshooting

​Server Not Appearing in Claude

​Browser Not Launching

​Connection Errors

​Content Extraction Not Working

​Limitations

​Comparison with MCP Client

​Code Examples

​See Also

Overview

Installation

Quick Start

1. Configure Claude Desktop

2. Restart Claude Desktop

3. Use Browser Automation

API Reference

Available Tools

Navigation Tools

`browser_navigate`

`browser_go_back`

Interaction Tools

`browser_click`

`browser_type`

`browser_scroll`

State & Content Tools

`browser_get_state`

`browser_extract_content`

Tab Management Tools

`browser_list_tabs`

`browser_switch_tab`

`browser_close_tab`

Tool Response Format

Configuration

Environment Variables

Browser Profile Settings

Advanced Usage

Running Standalone

Security Considerations

Implementation Details

Browser Session Management

Tool Categories

Error Handling

Troubleshooting

Server Not Appearing in Claude

Browser Not Launching

Connection Errors

Content Extraction Not Working

Limitations

Comparison with MCP Client

Code Examples

See Also