MCP Browser Agent is a Model Context Protocol (MCP) integration tool designed to provide Claude Desktop with autonomous browser automation capabilities. It enables Claude to interact with web content, manipulate DOM elements, execute JavaScript, and make API requests.
Purpose
The tool is primarily used to transform Claude Desktop into an AI agent capable of autonomously operating a browser. Through the MCP protocol, Claude can control a real headed browser to complete tasks such as web navigation, form filling, element clicking, screenshots, JavaScript execution, and API calls, thereby automating various technical workflows.
Key Capabilities
- Advanced browser automation: Navigate to any URL with support for custom loading strategies; capture full-page or element-level screenshots; perform precise DOM interactions (click, fill, select, hover); execute arbitrary JavaScript in the browser context and capture console logs.
- Powerful API client: Make HTTP requests (GET, POST, PUT, PATCH, DELETE); configure request headers and request body content; handle response data in JSON format; provide detailed error handling feedback.
- MCP resource management: Access browser console logs as resources; retrieve screenshots through the MCP resource interface; maintain persistent sessions of headed browser instances.
- AI agent capabilities: Chain multiple browser operations to complete complex tasks; follow multi-step instructions with intelligent error recovery; automate technical tasks through natural language instructions.
Usage
Requirements
- Node.js 20 or higher
- Browser: Google Chrome or a browser supported by Playwright (Chrome by default, WebKit, Firefox, Edge)
Installation
- Install via Smithery: Install the packaged bundle from the Smithery server page, or use the CLI.
- Manual installation: Clone or download the repository, install dependencies, and build the project.
Running the MCP server
There are two ways:
- Run manually: Open a terminal, navigate to the project directory, run the server directly, and keep the terminalwindow open.
- Start automatically with Claude Desktop (recommended): Edit the Claude Desktop 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), add the Browser Agent MCP configuration, and replace ABSOLUTE_PATH_TO_DIRECTORY with the actual installation path.
Browser selection
Multiple browser types are supported and can be specified through the configuration file, command-line arguments, environment variables, or the Claude Desktop configuration. Supported values: chrome (default), firefox, webkit, edge.
Use Cases
- Automating web searches and information extraction
- Form filling and submission
- Web page screenshots and visual content capture
- Executing JavaScript and retrieving console logs
- Directly calling APIs and processing returned data
- Automation of complex multi-step workflows
Limitations
- Requires Node.js 20 or higher.
- Requires a supported browser to be installed.
- Playwright browsers are not downloaded automatically on first use and must be installed manually (cloning and running npm install automatically downloads Chromium, Firefox, and WebKit; installing via Smithery or MCPB does not).
- On macOS 13 (Ventura), Playwright is pinned to version 1.61 because 1.62 no longer supports that version.
- Playwright does not directly support the Safari browser, but instead uses the WebKit engine.
- Selecting edge launches the installed Microsoft Edge, and falls back to Playwright's Chromium if Edge is not installed.
- Tool results before version 0.9.0 were in the legacy toolResult field, and current MCP clients only read content, becauseThis needs to be updated to version 0.9.0 or higher.
- Navigation may fail because the firewall blocks the browser binaries (ERR_NAME_NOT_RESOLVED), and the browser binaries under ~/Library/Caches/ms-playwright/ need to be allowed.
- The browser process may not shut down properly and needs to be terminated manually.
Technical Implementation
MCP Browser Agent is built on the Model Context Protocol and lets Claude interact with a headed browser through Playwright. The implementation includes four main components: the server (index.ts), the tool registry (tools.ts), the request handlers (handlers.ts), and the executor (executor.ts).
Available Resources
- browser://logs - Access browser console logs
- screenshot://[name] - Access screenshots by name
