A powerful Model Context Protocol (MCP) integration that provides Claude Desktop with autonomous browser automation capabilities. - 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
Add this skill
npx mdskills install imprvhub/mcp-browser-agentComprehensive browser automation MCP with excellent tool variety and clear setup docs
1# MCP Browser Agent23[](https://archestra.ai/mcp-catalog/imprvhub__mcp-browser-agent)4[](https://smithery.ai/server/@imprvhub/mcp-browser-agent)56<table style="border-collapse: collapse; width: 100%; table-layout: fixed;">7<tr>8<td style="width: 40%; padding: 15px; vertical-align: middle; border: none;">A powerful Model Context Protocol (MCP) integration that provides Claude Desktop with autonomous browser automation capabilities.</td>9<td style="width: 60%; padding: 0; vertical-align: middle; border: none; min-width: 300px; text-align: center;"><a href="https://glama.ai/mcp/servers/@imprvhub/mcp-browser-agent">10 <img style="max-width: 100%; height: auto; min-width: 300px;" src="https://glama.ai/mcp/servers/@imprvhub/mcp-browser-agent/badge" alt="Browser Agent MCP server" />11</a></td>12</tr>13</table>1415## Features1617- **Advanced Browser Automation**18 - Navigate to any URL with customizable load strategies19 - Capture full-page or element-specific screenshots20 - Perform precise DOM interactions (click, fill, select, hover)21 - Execute arbitrary JavaScript in browser context with console logs capture2223- **Powerful API Client**24 - Execute HTTP requests (GET, POST, PUT, PATCH, DELETE)25 - Configure request headers and body content26 - Process response data with JSON formatting27 - Error handling with detailed feedback2829- **MCP Resource Management**30 - Access browser console logs as resources31 - Retrieve screenshots through MCP resource interface32 - Persistent session with headful browser instance3334- **AI Agent Capabilities**35 - Chain multiple browser operations for complex tasks36 - Follow multi-step instructions with intelligent error recovery37 - Technical task automation through natural language instructions3839## Demo4041<p>42 <a href="https://www.youtube.com/watch?v=0lMsKiTy7TE">43 <img src="public/assets/preview.png" width="600" alt="Browser Agent MCP server demo" />44 </a>45</p>4647<details>48<summary> Timestamps: </summary>4950Click on any timestamp to jump to that section of the video5152[**00:00**](https://www.youtube.com/watch?v=0lMsKiTy7TE&t=0s) - **Google Search for MCP**53Navigation 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.5455[**00:33**](https://www.youtube.com/watch?v=0lMsKiTy7TE&t=33s) - **Screenshot Capture**56Taking 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.5758[**01:00**](https://www.youtube.com/watch?v=0lMsKiTy7TE&t=60s) - **Wikipedia Search**59Navigation 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.6061[**01:38**](https://www.youtube.com/watch?v=0lMsKiTy7TE&t=98s) - **Dropdown Menu Interaction I**62Navigation 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.6364[**01:56**](https://www.youtube.com/watch?v=0lMsKiTy7TE&t=116s) - **Dropdown Menu Interaction II**65Changing 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.6667[**02:09**](https://www.youtube.com/watch?v=0lMsKiTy7TE&t=129s) - **Login Form Completion**68Navigation 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.6970[**02:28**](https://www.youtube.com/watch?v=0lMsKiTy7TE&t=148s) - **Login Submission**71Submitting the login credentials and completing the authentication process. Shows Claude's ability to trigger form submissions and navigate through multi-step processes.7273[**02:36**](https://www.youtube.com/watch?v=0lMsKiTy7TE&t=156s) - **API Request Execution**74Performing 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.75</details>7677## Requirements7879- Node.js 16 or higher80- Claude Desktop81- Playwright dependencies8283### Browser Support8485```bash86npm init playwright@latest87```8889This 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:9091- Chrome (default)92- Firefox93- Microsoft Edge94- WebKit (Safari engine)9596When 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:9798```99npx playwright install chrome100npx playwright install firefox101npx playwright install webkit102npx playwright install msedge103```104105> **Note about Safari**: Playwright doesn't provide direct support for Safari browser. Instead, it uses WebKit, which is the browser engine that powers Safari.106>107> **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.108## Installation109110### Installing Manually1111. Clone or download this repository:112```113git clone https://github.com/imprvhub/mcp-browser-agent114cd mcp-browser-agent115```1161172. Install dependencies:118```119npm install120```1211223. Build the project:123```124npm run build125```126127## Running the MCP Server128129There are two ways to run the MCP server:130131### Option 1: Running manually1321331. Open a terminal or command prompt1342. Navigate to the project directory1353. Run the server directly:136137```138node dist/index.js139```140141Keep this terminal window open while using Claude Desktop. The server will run until you close the terminal.142143### Option 2: Auto-starting with Claude Desktop (recommended for regular use)144145The Claude Desktop can automatically start the MCP server when needed. To set this up:146147#### Configuration148149The Claude Desktop configuration file is located at:150151- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`152- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`153- **Linux**: `~/.config/Claude/claude_desktop_config.json`154155Edit this file to add the Browser Agent MCP configuration. If the file doesn't exist, create it:156157```json158{159 "mcpServers": {160 "browserAgent": {161 "command": "node",162 "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",163 "--browser",164 "chrome"165 ]166 }167 }168}169```170171**Important**: Replace `ABSOLUTE_PATH_TO_DIRECTORY` with the **complete absolute path** where you installed the MCP172 - macOS/Linux example: `/Users/username/mcp-browser-agent`173 - Windows example: `C:\\Users\\username\\mcp-browser-agent`174175If 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:176177```json178{179 "mcpServers": {180 "otherMcp1": {181 "command": "...",182 "args": ["..."]183 },184 "otherMcp2": {185 "command": "...",186 "args": ["..."]187 },188 "browserAgent": {189 "command": "node",190 "args": [191 "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",192 "--browser",193 "chrome"194 ]195 }196 }197}198```199200## Browser Selection201202The MCP Browser Agent supports multiple browser types. By default, it uses Chrome, but you can specify a different browser in several ways:203204### Option 1: Configuration File205206Create or edit the file `.mcp_browser_agent_config.json` in your home directory:207208```json209{210 "browserType": "chrome"211}212```213214Supported values for `browserType` are:215- `chrome` - Uses installed Chrome (default)216- `firefox` - Uses Firefox 'Nightly' browser217- `webkit` - Uses WebKit engine (Note: This is not Safari itself but the WebKit rendering engine that powers Safari)218- `edge` - Uses Microsoft Edge219220> **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.221222### Option 2: Command Line Argument223224When starting the MCP server manually, you can specify the browser type:225226```227node dist/index.js --browser firefox228```229230### Option 3: Environment Variable231232Set the `MCP_BROWSER_TYPE` environment variable:233234```235MCP_BROWSER_TYPE=firefox node dist/index.js236```237238### Option 4: Claude Desktop Configuration239240When configuring the MCP in Claude Desktop's `claude_desktop_config.json`, you can specify the browser type:241242```json243{244 "mcpServers": {245 "browserAgent": {246 "command": "node",247 "args": [248 "ABSOLUTE_PATH_TO_DIRECTORY/mcp-browser-agent/dist/index.js",249 "--browser",250 "chrome"251 ]252 }253 }254}255```256257## Technical Implementation258259MCP 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:2602611. **Server (index.ts)**262 - Initializes the MCP server with Model Context Protocol standard protocol263 - Configures server capabilities for tools and resources264 - Establishes communication with Claude through the stdio transport2652662. **Tools Registry (tools.ts)**267 - Defines browser and API tool schemas268 - Specifies parameters, validation rules, and descriptions269 - Registers tools with the MCP server for Claude's discovery2702713. **Request Handlers (handlers.ts)**272 - Manages MCP protocol requests for tools and resources273 - Exposes browser logs and screenshots as queryable resources274 - Routes tool execution requests to the appropriate handlers2752764. **Executor (executor.ts)**277 - Manages browser and API client lifecycle278 - Implements browser automation functions using Playwright279 - Handles API requests with proper error handling and response parsing280 - Maintains stateful browser session between commands281282### Agent Capabilities283284Unlike basic integrations, MCP Browser Agent functions as a true AI agent by:285286- Maintaining persistent browser state across multiple commands287- Capturing detailed console logs for debugging288- Storing screenshots for reference and review289- Managing complex interaction sequences290- Providing detailed error information for recovery291- Supporting chained operations for complex workflows292293## Available Tools294295### Browser Tools296297| Tool Name | Description | Parameters |298|-----------|-------------|------------|299| `browser_navigate` | Navigate to a URL | `url` (required), `timeout`, `waitUntil` |300| `browser_screenshot` | Capture screenshot | `name` (required), `selector`, `fullPage`, `mask`, `savePath` |301| `browser_click` | Click element | `selector` (required) |302| `browser_fill` | Fill form input | `selector` (required), `value` (required) |303| `browser_select` | Select dropdown option | `selector` (required), `value` (required) |304| `browser_hover` | Hover over element | `selector` (required) |305| `browser_evaluate` | Execute JavaScript | `script` (required) |306307### API Tools308309| Tool Name | Description | Parameters |310|-----------|-------------|------------|311| `api_get` | GET request | `url` (required), `headers` |312| `api_post` | POST request | `url` (required), `data` (required), `headers` |313| `api_put` | PUT request | `url` (required), `data` (required), `headers` |314| `api_patch` | PATCH request | `url` (required), `data` (required), `headers` |315| `api_delete` | DELETE request | `url` (required), `headers` |316317## Resource Access318319The MCP Browser Agent exposes the following resources:320321- `browser://logs` - Access browser console logs322- `screenshot://[name]` - Access screenshots by name323324325## Example Usage326327Here are some realistic examples of how to use the MCP Browser Agent with Claude:328329### Basic Browser Navigation330331```332Navigate to the Google homepage at https://www.google.com333```334335```336Take a screenshot of the current page and name it "google-homepage"337```338339```340Type "weather forecast" in the search box341```342343### Simple Interactions344345```346Navigate to https://www.wikipedia.org and search for "Model Context Protocol"347```348349```350Go to https://the-internet.herokuapp.com/dropdown and select the option "Option 1" from the dropdown351```352353### Basic Form Filling354355```356Navigate to https://the-internet.herokuapp.com/login and fill in the username field with "tomsmith" and the password field with "SuperSecretPassword!"357```358359```360Go to https://the-internet.herokuapp.com/login, fill in the username and password fields, then click the login button361```362363### Simple JavaScript Execution364365```366Go to https://example.com and execute a JavaScript script to return the page title367```368369```370Navigate to https://www.google.com and execute a JavaScript script to count the number of links on the page371```372373### Basic API Requests374375```376Perform a GET request to https://jsonplaceholder.typicode.com/todos/1377```378379```380Make a POST request to https://jsonplaceholder.typicode.com/posts with appropriate JSON data381```382383These examples represent the actual capabilities of the MCP Browser Agent and are more realistic about what it can accomplish in its current state.384385## Troubleshooting386387### "Server disconnected" error388If you see the error "MCP Browser Agent: Server disconnected" in Claude Desktop:3893901. **Verify the server is running**:391 - Open a terminal and manually run `node dist/index.js` from the project directory392 - If the server starts successfully, use Claude while keeping this terminal open3933942. **Check your configuration**:395 - Ensure the absolute path in `claude_desktop_config.json` is correct for your system396 - Double-check that you've used double backslashes (`\\`) for Windows paths397 - Verify you're using the complete path from the root of your filesystem398399### Browser not appearing400If the browser doesn't launch or you don't see it:4014021. **Check if the specified browser is installed**403 - Verify that you have the browser (Chrome, Firefox, Edge, or Safari/WebKit) installed on your system404 - The browser drivers are handled automatically by Playwright4054062. **Restart the server and Claude Desktop**407 - Kill any existing node processes that might be running the server408 - Restart Claude Desktop to establish a fresh connection409410### Browser process not closing properly411There are known issues with Chromium and Chrome browsers where the process sometimes doesn't terminate properly after use. If you experience this issue:4124131. **Manually close the browser process**:414 - **Windows**: Press Ctrl+Shift+Esc to open Task Manager, find the Chrome/Chromium process and end it415 - **macOS**: Open Activity Monitor (Applications > Utilities > Activity Monitor), find the Chrome/Chromium process and click the X to terminate it416 - **Linux**: Run `ps aux | grep chrome` or `ps aux | grep chromium` to find the process, then `kill <PID>` to terminate it4174182. **Note about browser compatibility**:419 - This issue has been observed primarily with Chromium and Chrome420 - Firefox and Playwright's built-in browser don't typically experience this problem421422> [!CAUTION]423> This MCP integration is built on Playwright, which has known issues and bugs that may affect its operation. Please report any issues you encounter with the browser automation to [Playwright's GitHub issues](https://github.com/microsoft/playwright/issues). The Playwright team is continuously working to address these issues, but this agent provides a foundation for browser automation capabilities with Claude Desktop despite these limitations.424425## Development426427### Project Structure428429- `src/index.ts`: Main entry point and MCP server initialization430- `src/tools.ts`: Tool schemas and registration431- `src/handlers.ts`: MCP request handlers for tools and resources432- `src/executor.ts`: Tool implementation logic using Playwright433434### Building435436```437npm run build438```439440### Watching for Changes441442```443npm run watch444```445446## Testing447448The project includes tests to verify core functionality and browser handling.449450```451npm test # Run tests452npm run test:watch # Watch mode453npm run test:coverage # Coverage report454```455456Tests verify configuration integrity, browser automation features, error handling, and process cleanup. The test suite focuses particularly on ensuring proper handling of browser processes due to known issues with Chrome/Chromium termination.457458## Security Considerations459460> [!IMPORTANT]461> This MCP integration provides Claude with autonomous browser control capabilities. Please review our [Security Policy](SECURITY.md) for important information about prohibited uses, security implications, and best practices.462463The MCP Browser Agent is designed for legitimate automation tasks but could potentially be misused. Users are responsible for ensuring their use complies with all applicable laws, terms of service, and ethical guidelines. See our detailed [Security Policy](SECURITY.md) for more information.464465## Contributing466467Contributions to the MCP Browser Agent are welcome! Here are some areas where you can help:468469- Adding new browser automation capabilities470- Improving error handling and recovery471- Enhancing screenshot and resource management472- Creating useful workflows and examples473- Optimizing performance for complex operations474475## License476477This project is licensed under the Mozilla Public License 2.0 - see the [LICENSE](https://github.com/imprvhub/mcp-browser-agent/blob/main/LICENSE) file for details.478479## Related Links480481- [Model Context Protocol](https://modelcontextprotocol.io/)482- [Claude Desktop](https://claude.ai/download)483- [Playwright Documentation](https://playwright.dev/docs/intro)484- [MCP Series](https://github.com/mcp-series)485
Full transparency — inspect the skill content before installing.