agent-browser-mcp

An MCP service that lets your Agent directly operate the "real Chrome you are currently using."

It is not a sandbox browser, nor a simple web scraper; it connects to the Chrome instance already open on your machine, preserving:

• Login states

• Cookies

• Open tabs

• Real page context

Suitable for scenarios such as:

• Allowing Hermes to directly read your Xiaohongshu, backend systems, knowledge bases, or management console pages

• Automating websites you are already logged into, rather than logging into a stateless browser again

• Switching to CDP / real mouse and keyboard operations when standard browser automation is unstable

• Having page scanning, JS execution, CDP control, screenshots, and physical input all in one MCP tool

In a nutshell:

This is a project that wraps "real browser automation" into a standard MCP, allowing Agents to move beyond sandbox browsers and truly enter your daily browser workflow.

Core Capabilities Overview

• Real Chrome tab discovery and switching

• Page scanning and simplified content extraction

• In-page JavaScript execution

• Native CDP single-command / batch execution

• Page screenshots / Desktop screenshots

• Cookie reading

• Mouse movement, clicking, and dragging

• Keyboard input and hotkeys

If you want Hermes, Claude Desktop, Cursor, or other MCP clients to directly operate your local real browser, this project is designed for that scenario.

Related MCP server: Chrome MCP Server

What this MCP can do

This project wraps real browser automation capabilities into standard MCP tools, with key features including:

1. Browser Tabs and Navigation

• View currently connected real tabs

• Switch to a specified tab

• Open a URL in the current tab

• Open a new tab

2. Page Reading

• Scan current page content

• Extract simplified HTML / text

• Suitable for reading information feeds, post lists, and search result pages

3. Page Execution and CDP Control

• Execute arbitrary JavaScript on the page

• Directly call Chrome DevTools Protocol (CDP)

• Support for single and batch commands

• Can be used for screenshots, DOM queries, clicks, file uploads, and more complex operations

4. Screenshot Capabilities

• Page screenshots (via CDP)

• Desktop screenshots (for assisting with real desktop operations)

5. Real Physical Input

• Mouse movement

• Mouse clicking

• Mouse dragging

• Keyboard input

• Hotkey sending

These capabilities are well-suited for handling:

• Websites that must maintain a login state

• Websites where standard browser automation tools are easily flagged by risk control

• Scenarios requiring real clicks / real keyboard input

• Scenarios requiring the reading of complex page structures

Suitable Scenarios

For example:

• Using Hermes to read your current Xiaohongshu homepage recommendation feed

• Opening a backend page in a real browser and scraping information

• Calling CDP to take a page screenshot

• Falling back to real mouse/keyboard operations when page JS is insufficient

• Letting an Agent directly operate a site you are already logged into, instead of re-logging into a stateless browser

How it Works

The project consists of three layers:

1. Chrome Extension

• Injected into real web pages

• Accesses tabs / cookies / debugger / management via Chrome API

• Communicates with the local bridge service

2. TMWebDriver Local Bridge

• Default listening:

  • WebSocket: 127.0.0.1:18765

  • HTTP: 127.0.0.1:18766

• Responsible for connecting the extension, maintaining sessions, and forwarding execution results

3. MCP Service

• Exposes browser capabilities as MCP tools

• For direct invocation by clients like Hermes, Claude Desktop, and Cursor

Main Tools

Currently exposed main MCP tools include:

Browser/Tabs

• get_setup_status

• list_tabs

• switch_tab

• open_url

• open_new_tab

• extension_path

• list_extensions

Page Reading/Execution

• scan_page

• execute_js

CDP and Screenshots

• cdp_command

• cdp_batch

• get_cookies

• capture_page_screenshot

• capture_desktop_screenshot

Physical Input

• mouse_move

• mouse_click

• mouse_drag

• type_text

• hotkey

• pointer_info

Installation Requirements

Recommended environment:

• macOS or Windows

• Python 3.10+

• Google Chrome

• Any MCP-compatible client, such as:

  • Hermes Agent

  • Claude Desktop

  • Cursor

Installation

After cloning locally, execute:

cd agent-browser-mcp
pip install -e .

If you want to build the wheel before installing:

python -m pip install --upgrade build
python -m build
pip install dist/agent_browser_mcp-0.1.0-py3-none-any.whl

Command Line Tools

After installation, a CLI is provided:

agent-browser-mcp

It has several common subcommands:

Output Chrome Extension Directory

agent-browser-mcp extension-path

Output Hermes Configuration Snippet

agent-browser-mcp print-hermes-config

Environment Diagnostics

agent-browser-mcp doctor

This command outputs JSON to help you check:

• Extension directory location

• Whether config.js is generated

• Port status

• Number of currently connected tabs

• Next steps/suggestions

Chrome Extension Installation

This project includes an unpacked Chrome extension that needs to be loaded manually once.

Step 1: Get the Extension Directory

agent-browser-mcp extension-path

Step 2: Load in Chrome

Open:

chrome://extensions

Then:

• Enable "Developer mode"

• Click "Load unpacked"

• Select the directory output in the previous step

Step 3: Open a Normal Web Page

Note: Do not stay on about:blank.

Please open a normal web page in Chrome, such as:

• https://www.baidu.com

• https://www.xiaohongshu.com

Otherwise, a valid session will not be established.

Hermes Configuration

Add the following to ~/.hermes/config.yaml:

mcp_servers:
  agent_browser:
    command: agent-browser-mcp
    timeout: 120
    connect_timeout: 60

The project also includes an example file:

• examples/hermes-config.yaml

After configuration, restart Hermes or reload the MCP.

You can verify with the following command:

hermes mcp list
hermes mcp test agent_browser

If the test is successful, Hermes will be able to discover and call these browser tools.

Claude Desktop / Cursor Configuration

Examples are also provided in the repository:

• examples/claude-desktop-config.json

• examples/cursor-mcp.json

The configuration structure is very simple; the core is:

{
  "mcpServers": {
    "agent_browser": {
      "command": "agent-browser-mcp",
      "args": []
    }
  }
}

Typical Usage Workflow

1. Install the Python package

2. Load the extension in Chrome

3. Open a real web page

4. Connect this service in an MCP client

5. Start calling browser tools

For example, an Agent can:

• Open the Xiaohongshu homepage

• Read the recommendation feed

• Scan the post list

• Take a CDP screenshot of the page

• Perform real mouse/keyboard operations when necessary

Security Warning

This project operates your real browser and real desktop.

This means:

• Mouse movements are real

• Clicks are real

• Input is real

• Hotkeys are real

• Login states in the browser are also real

Please use this only in MCP client and Agent environments you trust.

FAQ

1. Hermes can see the MCP service, but is not connected to any tabs

Please check:

• Whether the extension is already loaded in chrome://extensions

• Whether a normal web page is open in Chrome

• Whether it is just stuck on about:blank

You can also run:

agent-browser-mcp doctor

2. connected_tabs is 0

Usually due to one of the following reasons:

• The extension did not load successfully

• No normal web page is currently open

• The extension was just reloaded and the page has not refreshed yet

Suggestions:

• Refresh the current page

• Open a new normal URL

• Run doctor again

3. Physical input does not work on macOS

Please grant system permissions to the terminal / MCP client:

• Accessibility

• Screen Recording (if you need desktop screenshots)

4. hermes mcp test agent_browser fails

Please check:

• Whether the package was installed successfully

• Whether agent-browser-mcp is in the PATH

• Whether the Hermes configuration is correct

• Run agent-browser-mcp doctor to see diagnostic output

Acknowledgments

The browser automation capabilities of this project were extracted from the GenericAgent browser stack and re-packaged as an MCP service.

Special thanks to the GenericAgent project and its author for providing the original implementation ideas and core capabilities.

Original project address:

• https://github.com/lsdefine/GenericAgent

The following parts of this project are from or adapted from GenericAgent:

• TMWebDriver.py

• simphtml.py

• tmwd_cdp_bridge Chrome extension resources

If you continue to develop or publish based on this project, it is recommended to retain the acknowledgments and source attribution to GenericAgent.

License

MIT