335234131
agent-browser-mcp
MCP server that lets AI agents directly control your real Chrome browser with preserved login states, cookies, and tabs.
Repository last updated Apr 15, 2026
Overview
Agent-browser-mcp is a Model Context Protocol (MCP) server that bridges AI agents with a user's active Chrome browser session. Unlike sandboxed browsers or simple scrapers, it connects to the Chrome instance you already have open, preserving all login states, cookies, open tabs, and page contexts. This enables agents to interact with authenticated websites and complex web applications as if a human were using them.
The system consists of three layers: a Chrome extension injected into real web pages, a local bridge service (TMWebDriver) that communicates with the extension, and the MCP server that exposes browser capabilities as standard MCP tools. The bridge listens on WebSocket port 18765 and HTTP port 18766 by default, managing sessions and forwarding commands.
This project is ideal for scenarios where agents need to read content from logged-in platforms (e.g., Xiaohongshu, admin dashboards), automate workflows on sites with anti-bot measures, or combine page scanning with physical mouse/keyboard inputs. It works with any MCP client such as Hermes Agent, Claude Desktop, or Cursor.
Highlights
- Operates real Chrome sessions with preserved login states and cookies
- Executes native CDP commands for advanced DOM and browser control
- Supports physical mouse and keyboard inputs for human-like automation
- Provides page scanning, JavaScript execution, and screenshot capabilities
- Works with Hermes, Claude Desktop, Cursor, and other MCP clients
- Includes a diagnostic CLI tool for troubleshooting connections
Features
Real Browser Control
Connects to your active Chrome session, maintaining login states, cookies, and open tabs for authenticated automation.
CDP and JavaScript Execution
Execute arbitrary JavaScript, send single or batch Chrome DevTools Protocol commands for fine-grained browser control.
Physical Input Automation
Perform real mouse movements, clicks, drags, keyboard typing, and hotkeys for scenarios where programmatic automation is insufficient.
Page Scanning and Screenshots
Scan page content, extract simplified HTML/text, capture page or desktop screenshots via CDP.
Multi-Client Support
Compatible with Hermes Agent, Claude Desktop, Cursor, and any MCP client; includes example configs for each.
Diagnostic CLI
Built-in <code>agent-browser-mcp doctor</code> command outputs JSON diagnostics for extension status, port state, and connected tabs.
Requirements
- Python 3.10+
- Google Chrome
- macOS or Windows
- MCP client (Hermes Agent, Claude Desktop, or Cursor)
How it's built
The project is written in Python and structured as a standard Python package with a CLI entry point. The core components live under src/agent_browser_mcp/: server.py implements the MCP server, tmwebdriver.py provides the local bridge, and simphtml.py handles HTML simplification. The Chrome extension resides in chrome_extension/ and communicates with the bridge via WebSocket.
On startup, the MCP server launches the TMWebDriver bridge, which connects to the Chrome extension. The extension uses Chrome APIs to access tabs, cookies, and the debugger, enabling CDP commands. Physical input is handled via platform-specific libraries (e.g., PyAutoGUI on macOS/Windows). The server exposes each capability as a distinct MCP tool, such as list_tabs, execute_js, cdp_command, and mouse_click.
Integration with MCP clients requires adding the server to the client's configuration. For Hermes, add a YAML block to ~/.hermes/config.yaml; for Claude Desktop or Cursor, use the provided JSON examples. The CLI also provides print-hermes-config to output the exact configuration snippet.
Source
This summary was written for Neura Market from the project's own repository. Install commands, identifiers and licence details are reproduced unchanged. The 335234131/agent-browser-mcp repository is the authoritative source and the place to file issues or contribute.
Category: Browser Automation · Licensed under MIT