# Agent Browser Mcp

> 让 Agent 直接操作真实 Chrome 的 MCP 服务，支持页面扫描、CDP、截图与物理输入

- **Type:** MCP server
- **Install:** `agentstack add mcp-335234131-agent-browser-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [335234131](https://agentstack.voostack.com/s/335234131)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [335234131](https://github.com/335234131)
- **Source:** https://github.com/335234131/agent-browser-mcp

## Install

```sh
agentstack add mcp-335234131-agent-browser-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# agent-browser-mcp

让你的 Agent 直接操作“你正在使用的真实 Chrome”的 MCP 服务。

它不是沙盒浏览器，也不是简单网页抓取器，而是连接你本机已经打开的 Chrome，会保留：
- 登录状态
- Cookies
- 已打开标签页
- 真实页面上下文

适合这样的场景：
- 让 Hermes 直接读取你的小红书、后台系统、知识库、管理台页面
- 对已经登录的网站做自动化，而不是重新登录一个无状态浏览器
- 在普通浏览器自动化不稳定时，切换到 CDP / 真实鼠标键盘操作
- 在一个 MCP 工具里同时拥有：页面扫描、JS 执行、CDP 控制、截图、物理输入

一句话概括：
> 这是一个把“真实浏览器自动化”包装成标准 MCP 的项目，让 Agent 不再只会操作沙盒浏览器，而能真正进入你的日常浏览器工作流。

## 核心能力一览

- 真实 Chrome 标签页发现与切换
- 页面扫描与简化内容提取
- 页面内 JavaScript 执行
- 原生 CDP 单命令 / 批量调用
- 页面截图 / 桌面截图
- Cookies 读取
- 鼠标移动、点击、拖拽
- 键盘输入与热键

如果你希望让 Hermes、Claude Desktop、Cursor 等 MCP 客户端直接操作你本机真实浏览器，这个项目就是为这个场景准备的。

## 这个 MCP 能做什么

这个项目把真实浏览器自动化能力包装成了标准 MCP 工具，重点能力包括：

### 1. 浏览器标签页与导航
- 查看当前已连接的真实标签页
- 切换到指定标签页
- 在当前标签页打开 URL
- 新建标签页

### 2. 页面读取
- 扫描当前页面内容
- 提取简化后的 HTML / 文本
- 适合读取信息流、帖子列表、搜索结果页

### 3. 页面执行与 CDP 控制
- 在页面中执行任意 JavaScript
- 直接调用 Chrome DevTools Protocol（CDP）
- 支持单条命令和批量命令
- 可用于截图、DOM 查询、点击、文件上传等更复杂操作

### 4. 截图能力
- 页面截图（通过 CDP）
- 桌面截图（用于辅助真实桌面操作）

### 5. 真实物理输入
- 鼠标移动
- 鼠标点击
- 鼠标拖拽
- 键盘输入
- 热键发送

这类能力很适合处理：
- 必须保留登录态的网站
- 普通浏览器自动化工具容易被风控的网站
- 必须使用真实点击 / 真实键盘输入的场景
- 需要读取复杂页面结构的场景

## 适合哪些场景

例如：
- 用 Hermes 读取你当前小红书首页推荐流
- 在真实浏览器里打开后台页面并抓取信息
- 调用 CDP 截图页面
- 在页面 JS 不够用时，回退到真实鼠标/键盘操作
- 让 Agent 直接操作你已登录的网站，而不是重新登录一个无状态浏览器

## 工作原理

项目由三层组成：

1. Chrome 扩展
- 注入到真实网页
- 通过 Chrome API 访问 tabs / cookies / debugger / management
- 与本地桥接服务通信

2. TMWebDriver 本地桥接
- 默认监听：
  - WebSocket: `127.0.0.1:18765`
  - HTTP: `127.0.0.1:18766`
- 负责连接扩展、维护会话、转发执行结果

3. MCP 服务
- 把浏览器能力暴露为 MCP tools
- 供 Hermes、Claude Desktop、Cursor 等客户端直接调用

## 主要工具

当前暴露的主要 MCP 工具包括：

### 浏览器/标签页
- `get_setup_status`
- `list_tabs`
- `switch_tab`
- `open_url`
- `open_new_tab`
- `extension_path`
- `list_extensions`

### 页面读取/执行
- `scan_page`
- `execute_js`

### CDP 与截图
- `cdp_command`
- `cdp_batch`
- `get_cookies`
- `capture_page_screenshot`
- `capture_desktop_screenshot`

### 物理输入
- `mouse_move`
- `mouse_click`
- `mouse_drag`
- `type_text`
- `hotkey`
- `pointer_info`

## 安装要求

推荐环境：
- macOS 或 Windows
- Python 3.10+
- Google Chrome
- 任意支持 MCP 的客户端，例如：
  - Hermes Agent
  - Claude Desktop
  - Cursor

## 安装

在本地克隆后执行：

```bash
cd agent-browser-mcp
pip install -e .
```

如果你想先构建 wheel 再安装：

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

## 命令行工具

安装后会提供一个 CLI：

```bash
agent-browser-mcp
```

它有几个常用子命令：

### 输出 Chrome 扩展目录

```bash
agent-browser-mcp extension-path
```

### 输出 Hermes 配置片段

```bash
agent-browser-mcp print-hermes-config
```

### 环境诊断

```bash
agent-browser-mcp doctor
```

这个命令会输出 JSON，帮助你检查：
- 扩展目录位置
- `config.js` 是否生成
- 端口状态
- 当前连接到的标签页数量
- 下一步建议

## Chrome 扩展安装

这个项目包含一个 unpacked Chrome 扩展，需要手动加载一次。

### 第一步：获取扩展目录

```bash
agent-browser-mcp extension-path
```

### 第二步：在 Chrome 中加载

打开：

```text
chrome://extensions
```

然后：
- 打开“开发者模式”
- 点击“加载已解压的扩展程序”
- 选择上一步输出的目录

### 第三步：打开正常网页

注意不要停留在 `about:blank`。

请在 Chrome 中打开一个正常网页，例如：
- `https://www.baidu.com`
- `https://www.xiaohongshu.com`

否则不会建立有效会话。

## Hermes 配置

把下面这段加到 `~/.hermes/config.yaml`：

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

项目里也附带了示例文件：
- `examples/hermes-config.yaml`

配置后，重启 Hermes 或重新加载 MCP。

可用下面的命令验证：

```bash
hermes mcp list
hermes mcp test agent_browser
```

如果测试成功，Hermes 就能发现并调用这些浏览器工具。

## Claude Desktop / Cursor 配置

仓库中也放了示例：
- `examples/claude-desktop-config.json`
- `examples/cursor-mcp.json`

配置结构都很简单，核心就是：

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

## 典型使用流程

1. 安装 Python 包
2. 在 Chrome 中加载扩展
3. 打开一个真实网页
4. 在 MCP 客户端中接入这个服务
5. 开始调用浏览器工具

例如，Agent 可以做：
- 打开小红书首页
- 读取推荐流
- 扫描帖子列表
- 对页面进行 CDP 截图
- 在必要时执行真实鼠标/键盘操作

## 安全提醒

这个项目操作的是你的真实浏览器和真实桌面。

这意味着：
- 鼠标移动是真的
- 点击是真的
- 输入是真的
- 热键是真的
- 浏览器里的登录态也是真的

请只在你信任的 MCP 客户端和 Agent 环境中使用。

## 常见问题

### 1. Hermes 能看到 MCP 服务，但没有连接到任何标签页

请检查：
- 扩展是否已经在 `chrome://extensions` 中加载
- Chrome 里是否打开了正常网页
- 是否只是停留在 `about:blank`

你也可以运行：

```bash
agent-browser-mcp doctor
```

### 2. `connected_tabs` 为 0

通常是以下原因之一：
- 扩展没有加载成功
- 当前没有正常网页
- 扩展刚重载，页面还没刷新

建议：
- 刷新当前网页
- 新开一个正常 URL
- 再运行一次 `doctor`

### 3. 物理输入在 macOS 上不生效

请给终端 / MCP 客户端授予系统权限：
- 辅助功能（Accessibility）
- 屏幕录制（如果你需要桌面截图）

### 4. `hermes mcp test agent_browser` 失败

请检查：
- 包是否安装成功
- `agent-browser-mcp` 是否在 PATH 中
- Hermes 配置是否正确
- 运行 `agent-browser-mcp doctor` 看诊断输出

## 致谢

这个项目的浏览器自动化能力，是从 GenericAgent 的浏览器栈中提取并重新封装成 MCP 服务的。

特别感谢 GenericAgent 项目及其作者提供的原始实现思路与核心能力来源。

原项目地址：
- https://github.com/lsdefine/GenericAgent

本项目中以下部分来自或改编自 GenericAgent：
- `TMWebDriver.py`
- `simphtml.py`
- `tmwd_cdp_bridge` Chrome 扩展资源

如果你基于本项目继续二次开发或发布，也建议保留对 GenericAgent 的致谢与来源说明。

## 许可证

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [335234131](https://github.com/335234131)
- **Source:** [335234131/agent-browser-mcp](https://github.com/335234131/agent-browser-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-335234131-agent-browser-mcp
- Seller: https://agentstack.voostack.com/s/335234131
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.