Browser Automation MCP server

This MCP Browser Use tool enables AI agents to automate web tasks through browser control, including navigation, clicking, form filling, and scraping—all using natural language instructions via Claude's Model Context Protocol (MCP).

Installation

Prerequisites

• Python environment
• Claude AI assistant (desktop version)

Setup Steps

1. Clone the repository to your local machine:

   git clone https://github.com/janspoerer/mcp_browser_use.git
   cd mcp_browser_use
   

2. Create a virtual environment and install dependencies:

   python -m venv .venv
   source .venv/bin/activate  # On Windows, use .venv\Scripts\activate
   pip install -r requirements.txt
   

3. Configure the MCP in Claude's configuration file:

   • On macOS, locate or create this file: /Users/yourname/Library/Application Support/Claude/claude_desktop_config.json
   • Add the MCP server configuration:

   {
       "mcpServers": {
           "mcp_browser_use": {
               "command": "/Users/yourname/code/mcp_browser_use/.venv/bin/python",
               "args": [
                   "/Users/yourname/code/mcp_browser_use/mcp_browser_use"
               ]
           }
       }
   }
   

4. Restart Claude to apply the configuration.

Using the Browser MCP

Verifying Setup

1. After restarting Claude, look for a small hammer icon in the bottom-right of the "New Chat" window.
2. The number next to the hammer indicates how many functions the MCP provides.
3. Click the hammer to view all available browser automation functions.

Available Functions

Starting a Browser Session

start_browser

• Begins a new browser session.
• Parameters:
  • headless: Boolean indicating whether to run in headless mode.

Navigating to Websites

navigate

• Navigates to a specific URL.
• Parameters:
  • session_id: ID of the browser session.
  • url: The website URL to navigate to.

Interacting with Page Elements

click_element

• Clicks an element on the webpage.
• Parameters:
  • session_id: ID of the browser session.
  • selector: CSS selector, XPath, or ID of the element.
  • selector_type: Type of selector (css, xpath, id).

fill_text

• Enters text into an input field.
• Parameters:
  • session_id: ID of the browser session.
  • selector: Selector for the input field.
  • text: Text to enter.
  • selector_type: Type of selector.
  • clear_first: Whether to clear the field first.

send_keys

• Sends keyboard keys to the browser.
• Parameters:
  • session_id: ID of the browser session.
  • key: Key to send (ENTER, TAB, etc.).
  • selector: Optional selector for a specific element.
  • selector_type: Type of selector.

Page Manipulation

scroll

• Scrolls the page.
• Parameters:
  • session_id: ID of the browser session.
  • x: Horizontal scroll amount in pixels.
  • y: Vertical scroll amount in pixels.

take_screenshot

• Captures a screenshot of the current page.
• Parameters:
  • session_id: ID of the browser session.

Closing the Browser

close_browser

• Closes a browser session.
• Parameters:
  • session_id: ID of the browser to close.

Example Workflow

1. Ask Claude to start a browser session: "Can you start a browser session for me?"

2. Navigate to a website: "Please navigate to https://example.com"

3. Interact with elements: "Click the login button with id 'login-btn'"

4. Fill out forms: "Fill the username field with 'myusername' and the password field"

5. Take a screenshot of the result: "Take a screenshot of the current page"

6. Close the session when finished: "Please close the browser session"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp_browser_use" '{"command":"/Users/janspoerer/code/mcp_browser_use/.venv/bin/python","args":["/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mcp_browser_use": {
            "command": "/Users/janspoerer/code/mcp_browser_use/.venv/bin/python",
            "args": [
                "/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp_browser_use": {
            "command": "/Users/janspoerer/code/mcp_browser_use/.venv/bin/python",
            "args": [
                "/Users/janspoerer/code/mcp_browser_use/mcp_browser_use"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect