Content
# Tool List
Let your Agent directly operate the real Chrome browser's MCP service.
It's not a sandbox browser or a simple web scraper, but a connection to your locally opened Chrome browser, preserving:
- Login state
- Cookies
- Opened tabs
- Real page context
Suitable for scenarios such as:
- Let Hermes directly read your Xiaohongshu, backend system, knowledge base, management page
- Automate already logged-in websites instead of logging into a stateless browser
- Switch to CDP/real mouse and keyboard operations when ordinary browser automation is unstable
- Have page scanning, JS execution, CDP control, screenshot, and physical input in one MCP tool
In one sentence:
> This project packages real browser automation into a standard MCP, allowing Agents to operate not only on sandbox browsers but also on your daily browser workflow.
## Core Capabilities
- Real Chrome tab discovery and switching
- Page scanning and simplified content extraction
- Page JavaScript execution
- Native CDP single command/batch call
- Page screenshot/desktop screenshot
- Cookie reading
- Mouse movement, click, drag
- Keyboard input and hotkeys
If you want to let Hermes, Claude Desktop, Cursor, and other MCP clients directly operate your local real browser, this project is for this scenario.
## What This MCP Can Do
This project packages real browser automation capabilities into a standard MCP tool, focusing on:
### 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 the current page content
- Extract simplified HTML/text
- Suitable for reading information streams, post lists, search result pages
### 3. Page Execution and CDP Control
- Execute arbitrary JavaScript in the page
- Directly call Chrome DevTools Protocol (CDP)
- Support single command and batch commands
- Can be used for screenshot, DOM query, click, file upload, and other complex operations
### 4. Screenshot Capability
- Page screenshot (via CDP)
- Desktop screenshot (for auxiliary real desktop operation)
### 5. Real Physical Input
- Mouse movement
- Mouse click
- Mouse drag
- Keyboard input
- Hotkey sending
These capabilities are suitable for handling:
- Websites that must retain login state
- Websites where ordinary browser automation tools are easily wind-controlled
- Scenarios that require real click/real keyboard input
- Scenarios that require reading complex page structures
## Suitable Scenarios
For example:
- Use Hermes to read your current Xiaohongshu homepage recommendations
- Open a backend page in a real browser and grab information
- Call CDP to screenshot a page
- When page JS is insufficient, fall back to real mouse/keyboard operation
- Let the Agent directly operate your logged-in website instead of logging into a stateless browser
## Working Principle
The project consists of three layers:
1. Chrome Extension
- Injected into real web pages
- Access tabs/cookies/debugger/management via Chrome API
- Communicate with local bridge service
2. TMWebDriver Local Bridge
- Default listening:
- WebSocket: `127.0.0.1:18765`
- HTTP: `127.0.0.1:18766`
- Responsible for connecting extensions, maintaining sessions, and forwarding execution results
3. MCP Service
- Expose browser capabilities as MCP tools
- For Hermes, Claude Desktop, Cursor, and other clients to directly call
## Main Tools
The main MCP tools currently exposed 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 Screenshot
- `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-supported client, such as:
- Hermes Agent
- Claude Desktop
- Cursor
## Installation
Clone locally and execute:
```bash
cd agent-browser-mcp
pip install -e .
```
If you want to build a wheel and install it:
```bash
python -m pip install --upgrade build
python -m build
pip install dist/agent_browser_mcp-0.1.0-py3-none-any.whl
```
## Command-Line Tool
After installation, a CLI will be provided:
```bash
agent-browser-mcp
```
It has several common subcommands:
### Output Chrome Extension Directory
```bash
agent-browser-mcp extension-path
```
### Output Hermes Configuration Fragment
```bash
agent-browser-mcp print-hermes-config
```
### Environment Diagnosis
```bash
agent-browser-mcp doctor
```
This command will output JSON to help you check:
- Extension directory location
- `config.js` generation
- Port status
- Currently connected tab count
- Next-step suggestions
## Chrome Extension Installation
This project contains an unpacked Chrome extension that needs to be loaded manually.
### Step 1: Get Extension Directory
```bash
agent-browser-mcp extension-path
```
### Step 2: Load in Chrome
Open:
```text
chrome://extensions
```
Then:
- Open "Developer mode"
- Click "Load unpacked extension"
- Select the directory output in the previous step
### Step 3: Open a Normal Webpage
Note that do not stay on `about:blank`.
Please open a normal webpage 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`:
```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 MCP.
You can verify with the following command:
```bash
hermes mcp list
hermes mcp test agent_browser
```
If the test is successful, Hermes can discover and call these browser tools.
## Claude Desktop/Cursor Configuration
The repository also includes examples:
- `examples/claude-desktop-config.json`
- `examples/cursor-mcp.json`
The configuration structure is simple, and the core is:
```json
{
"mcpServers": {
"agent_browser": {
"command": "agent-browser-mcp",
"args": []
}
}
}
```
## Typical Usage Process
1. Install Python package
2. Load the extension in Chrome
3. Open a real webpage
4. Access this service in the MCP client
5. Start calling browser tools
For example, Agent can:
- Open Xiaohongshu homepage
- Read recommendations
- Scan post lists
- Screenshot pages via CDP
- Perform real mouse/keyboard operations when necessary
## Security Reminder
This project operates on your real browser and real desktop.
This means:
- Mouse movement is real
- Click is real
- Input is real
- Hotkey is real
- Login state in the browser is also real
Please only use it in trusted MCP clients and Agent environments.
## Frequently Asked Questions
### 1. Hermes Can See MCP Service but Not Connected to Any Tabs
Please check:
- Whether the extension is loaded in `chrome://extensions`
- Whether a normal webpage is open in Chrome
- Whether it is stuck on `about:blank`
You can also run:
```bash
agent-browser-mcp doctor
```
### 2. `connected_tabs` is 0
Usually due to one of the following reasons:
- Extension not loaded successfully
- No normal webpage currently
- Extension just reloaded, page not refreshed
Suggestions:
- Refresh the current webpage
- Open a new normal URL
- Run `doctor` again
### 3. Physical Input Not Working on macOS
Please grant system permissions to the terminal/MCP client:
- Accessibility
- Screen recording (if you need desktop screenshot)
### 4. `hermes mcp test agent_browser` Failed
Please check:
- Whether the package is installed successfully
- Whether `agent-browser-mcp` is in PATH
- Whether Hermes configuration is correct
- Run `agent-browser-mcp doctor` to see diagnostic output
## Acknowledgments
The browser automation capabilities of this project were extracted and repackaged into an MCP service from GenericAgent's browser stack.
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 come from or are 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 also recommended to retain the acknowledgment and source description of GenericAgent.
## License
MIT
