Browser Agent

MCP Browser Agent

Features

• Advanced Browser Automation

  • Navigate to any URL with customizable load strategies
  • Capture full-page or element-specific screenshots
  • Perform precise DOM interactions (click, fill, select, hover)
  • Execute arbitrary JavaScript in browser context with console logs capture

• Powerful API Client

  • Execute HTTP requests (GET, POST, PUT, PATCH, DELETE)
  • Configure request headers and body content
  • Process response data with JSON formatting
  • Error handling with detailed feedback

• MCP Resource Management

  • Access browser console logs as resources
  • Retrieve screenshots through MCP resource interface
  • Persistent session with headful browser instance

• AI Agent Capabilities

  • Chain multiple browser operations for complex tasks
  • Follow multi-step instructions with intelligent error recovery
  • Technical task automation through natural language instructions

Demo

Click on any timestamp to jump to that section of the video

00:00 - Google Search for MCP
Navigation to Google homepage and search for "Model Context Protocol". Demonstration of Claude Desktop using the MCP integration to perform a basic web search and process the results.

00:33 - Screenshot Capture
Taking a screenshot of the search results with a custom filename and showcasing it in Finder. Shows how Claude can capture and save visual content from web pages during browser automation.

01:00 - Wikipedia Search
Navigation to Wikipedia.org and search for "Model Context Protocol". Illustrates Claude's ability to interact with different websites and their search functionality through the MCP integration.

01:38 - Dropdown Menu Interaction I
Navigation to a test website (the-internet.herokuapp.com/dropdown) and selection of "Option 1" from a dropdown menu. Demonstrates Claude's capability to interact with form elements and make selections.

01:56 - Dropdown Menu Interaction II
Changing the selection to "Option 2" from the same dropdown menu. Shows Claude's ability to manipulate the same form element multiple times and make different selections.

02:09 - Login Form Completion
Navigation to a login page (the-internet.herokuapp.com/login) and filling in the username field with "tomsmith" and password field with "SuperSecretPassword!". Demonstrates form filling automation.

02:28 - Login Submission
Submitting the login credentials and completing the authentication process. Shows Claude's ability to trigger form submissions and navigate through multi-step processes.

02:36 - API Request Execution
Performing a GET request to JSONPlaceholder API endpoint. Demonstrates Claude's capability to make direct API calls and process the returned data through the MCP integration.

Requirements

• Node.js 16 or higher
• Claude Desktop
• Playwright dependencies

Browser Support

npm init playwright@latest

This package includes Playwright and the necessary dependencies for running browser automation. When you run npm install, the required Playwright dependencies will be installed. The package supports the following browsers:

• Chrome (default)
• Firefox
• Microsoft Edge
• WebKit (Safari engine)

When you first use a browser type, Playwright will automatically install the corresponding browser drivers as needed. You can also install them manually with the following commands:

npx playwright install chrome
npx playwright install firefox
npx playwright install webkit
npx playwright install msedge

Note about Safari: Playwright doesn't provide direct support for Safari browser. Instead, it uses WebKit, which is the browser engine that powers Safari.

Note about Edge: When selecting Edge as the browser type, the agent will actually launch Microsoft Edge (not Chromium). Technically, in Playwright, Edge is launched using the Chromium browser instance with the 'msedge' channel parameter because Microsoft Edge is based on Chromium.

Installation

Installing Manually

1. Clone or download this repository:

git clone https://github.com/imprvhub/mcp-browser-agent
cd mcp-browser-agent

1. Install dependencies:

npm install

1. Build the project:

npm run build

Running the MCP Server

There are two ways to run the MCP server:

Option 1: Running manually

1. Open a terminal or command prompt
2. Navigate to the project directory
3. Run the server directly:

node dist/index.js

Keep this terminal window open while using Claude Desktop. The server will run until you close the terminal.

Option 2: Auto-starting with Claude Desktop (recommended for regular use)

The Claude Desktop can automatically start the MCP server when needed. To set this up:

Configuration

The Claude Desktop configuration file is located at:

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

Edit this file to add the Browser Agent MCP configuration. If the file doesn't exist, create it:

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

Important: Replace ABSOLUTE_PATH_TO_DIRECTORY with the complete absolute path where you installed the MCP

• macOS/Linux example: /Users/username/mcp-browser-agent
• Windows example: C:\\Users\\username\\mcp-browser-agent

If you already have other MCPs configured, simply add the "browserAgent" section inside the "mcpServers" object. Here's an example of a configuration with multiple MCPs:

{
  "mcpServers": {
    "otherMcp1": {
      "command": "...",
      "args": ["..."]
    },
    "otherMcp2": {
      "command": "...",
      "args": ["..."]
    },
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
      "--browser",
      "chrome"
    ]
    }
  }
}

Browser Selection

The MCP Browser Agent supports multiple browser types. By default, it uses Chrome, but you can specify a different browser in several ways:

Option 1: Configuration File

Create or edit the file .mcp_browser_agent_config.json in your home directory:

{
  "browserType": "chrome"
}

Supported values for browserType are:

• chrome - Uses installed Chrome (default)
• firefox - Uses Firefox 'Nightly' browser
• webkit - Uses WebKit engine (Note: This is not Safari itself but the WebKit rendering engine that powers Safari)
• edge - Uses Microsoft Edge

Note about Safari: Playwright doesn't provide direct support for Safari browser. Instead, it uses WebKit, which is the browser engine that powers Safari. The WebKit implementation in Playwright provides similar functionality but is not identical to the Safari browser experience.

Option 2: Command Line Argument

When starting the MCP server manually, you can specify the browser type:

node dist/index.js --browser firefox

Option 3: Environment Variable

Set the MCP_BROWSER_TYPE environment variable:

MCP_BROWSER_TYPE=firefox node dist/index.js

Option 4: Claude Desktop Configuration

When configuring the MCP in Claude Desktop's claude_desktop_config.json, you can specify the browser type:

{
  "mcpServers": {
    "browserAgent": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",
        "--browser",
        "chrome"
      ]
    }
  }
}

Technical Implementation

MCP Browser Agent is built on the Model Context Protocol, enabling Claude to interact with a headful browser through Playwright. The implementation consists of four main components:

1. Server (index.ts)

   • Initializes the MCP server with Model Context Protocol standard protocol
   • Configures server capabilities for tools and resources
   • Establishes communication with Claude through the stdio transport

2. Tools Registry (tools.ts)

   • Defines browser and API tool schemas
   • Specifies parameters, validation rules, and descriptions
   • Registers tools with the MCP server for Claude's discovery

3. Request Handlers (handlers.ts)

   • Manages MCP protocol requests for tools and resources
   • Exposes browser logs and screenshots as queryable resources
   • Routes tool execution requests to the appropriate handlers

4. Executor (executor.ts)

   • Manages browser and API client lifecycle
   • Implements browser automation functions using Playwright
   • Handles API requests with proper error handling and response parsing
   • Maintains stateful browser session between commands

Agent Capabilities

Unlike basic integrations, MCP Browser Agent functions as a true AI agent by:

• Maintaining persistent browser state across multiple commands
• Capturing detailed console logs for debugging
• Storing screenshots for reference and review
• Managing complex interaction sequences
• Providing detailed error information for recovery
• Supporting chained operations for complex workflows

Available Tools

Browser Tools

API Tools

…