MCP Browser Agent

The MCP Browser Agent gives Claude Desktop autonomous browser automation through a persistent headful browser session. It lets you navigate web pages, interact with elements, capture screenshots, run JavaScript in the browser context, and perform API calls, all while maintaining state across commands for complex multi-step workflows.

How to use

You use the MCP Browser Agent by configuring it as an MCP server that Claude Desktop can communicate with. This agent keeps a browser session alive, logs console output, and exposes screenshots and logs as resources. You can chain browser operations with AI-driven instructions to perform tasks such as navigating to pages, filling forms, clicking elements, taking screenshots, and making API requests. Use it to automate multi-step tasks with error recovery and persistent context.

How to install

Prerequisites: Node.js 16 or higher, Claude Desktop, and Playwright dependencies.

# 1) Ensure Node.js is installed
node -v

# 2) Install dependencies for the MCP Browser Agent project
npm install

# 3) Build the project for production/runtime
npm run build

Configuration and running the MCP server

There is a local, auto-start option that lets Claude Desktop start the MCP Browser Agent when needed. Use the following configuration in Claude Desktop to run the agent as a local stdio server.

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

Browser selection

You can choose the browser type by passing a flag when starting the server or by configuring the client. The supported options map to the browser types available through Playwright and are used to launch the corresponding browser driver.

Two example approaches are shown here: configuring the runner in the server startup and using a CLI flag.

Troubleshooting

If you encounter issues where the MCP Browser Agent reports a server disconnect or the browser does not start, verify that the server process is running and that the absolute path in your configuration is correct. Restart Claude Desktop after making changes.

If the browser process does not terminate properly, manually terminate the browser process and consider using Firefox or WebKit for more stable termination behavior.

Security considerations

This MCP integration provides autonomous browser control and should be used in compliance with applicable laws, terms of service, and organizational policies. Exercise caution and review security practices when automating browser interactions and handling sensitive data.

Development

Key components of the MCP Browser Agent include the Server (index.ts), Tools Registry (tools.ts), Request Handlers (handlers.ts), and Executor (executor.ts). These parts together enable persistent browser sessions, resource access, and API interactions through Playwright.

Available tools

browser_navigate

Navigate to a URL with optional timeout and load strategy settings.

browser_screenshot

Capture a screenshot, with options for name, selector targeting, full-page capture, masking, and save path.

browser_click

Click a page element identified by a selector.

browser_fill

Fill a form input identified by a selector with a value.

browser_select

Select a dropdown option by value for a given selector.

browser_hover

Hover the mouse over a page element identified by a selector.

browser_evaluate

Execute arbitrary JavaScript in the browser context and capture results.

api_get

Perform an HTTP GET request to a URL with optional headers.

api_post

Perform an HTTP POST request with URL, data body, and headers.

api_put

Perform an HTTP PUT request with URL, data body, and headers.

api_patch

Perform an HTTP PATCH request with URL, data body, and headers.

api_delete

Perform an HTTP DELETE request to a URL with optional headers.