mcp-browser-agent

The MCP Browser Agent provides autonomous browser automation capabilities to Claude Desktop via a persistent browser instance. It enables advanced browser tasks such as navigating to URLs with configurable load strategies, capturing full-page or element-specific screenshots, and performing precise DOM interactions (click, fill, select, hover). It also exposes a powerful built-in API client that can execute HTTP requests (GET, POST, PUT, PATCH, DELETE) with configurable headers and bodies, and returns JSON-formatted responses with error handling. Additionally, the agent publishes browser console logs and screenshots as MCP resources, supports persistent sessions with a headful browser, and can chain multiple browser operations to accomplish complex tasks with intelligent error recovery through AI-assisted instruction parsing. You can drive these capabilities through Claude Desktop by starting the MCP server via the configured command and interacting with the available MCP endpoints and resources.

With an MCP-enabled workflow, you can issue multi-step browser automation sequences (e.g., navigate, fill a form, submit, then perform an API call and process results) and have Claude manage the logic, retries, and data extraction. The agent is designed to support growth, including multiple browser types and configurable load strategies, so you can tailor automation reliability to your targets and environments.

Prerequisites

• Node.js 16 or higher
• npm (comes with Node.js)
• Claude Desktop (for integration and control)
• Playwright dependencies (when using browser automation)

Install and set up

1. Clone the repository or download the package contents:

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

2. Install dependencies:

npm install

3. Build the project (produces dist/index.js):

npm run build

4. Run the MCP server manually (example):

node dist/index.js

5. Optional: Configure Claude Desktop to auto-start the MCP server by adding an MCP entry in the Claude configuration (example below uses a placeholder ABSOLUTE_PATH):

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

Tips and common considerations:

• When integrating with Claude Desktop, ensure ABSOLUTE_PATH_TO_DIRECTORY accurately points to the location where you installed the MCP Browser Agent.
• The default browser type is Chrome; you can switch to other supported browsers via the --browser flag or corresponding configuration.
• If Playwright dependencies are needed (for headless/headful browser operation), run the recommended Playwright setup commands (e.g., npm init playwright@latest) as described in the README to install required browser drivers.
• For sustained automation, you can enable a persistent, headful browser session to preserve state across tasks.
• If you encounter issues fetching or rendering pages, verify network access, firewall rules, and correct PATH configurations in your mcpServers setup.
• Ensure your Claude Desktop config.json uses absolute paths and valid JSON formatting to avoid startup errors.