内容
# Controlium
**让 Claude 控制你的真实 Chrome 浏览器。** Controlium 是一个 Chrome 扩展程序 + 本地 MCP
桥接器，它允许 Claude — 在 **Claude 代码** *和* **Claude 桌面版** — 通过 Chrome DevTools 协议控制你的浏览器：导航、点击、输入、滚动、截图、
读取页面、运行 JavaScript。它实现了官方的 "Chrome 中的 Claude" 扩展程序的功能，但有两点不同：
- 🔝 **将工作标签页带到前面。** 每个操作首先使目标标签页成为活动、可见的标签页，并聚焦其窗口。Claude 的标签页永远不会在后台被隐藏。（官方扩展程序故意驱动后台标签页 - 请参见
[RESEARCH.md](RESEARCH.md)。）
- ✨ **显示合成光标。** 一个发光的指针动画到每个点击位置，并带有涟漪效果，这样你就可以看到 Claude 的工作 - 它也会出现在截图中。
它在你的**正常 Chrome 配置文件**（你的登录信息、你的标签页）中运行，而不是在一个临时实例中。
```
Claude 代码 / Claude 桌面版 / Claude 工作 … （任意数量的 MCP 客户端）
│ stdio
▼
mcp-server/server.js （薄客户端；自动启动守护进程）
│ WebSocket → 127.0.0.1:8765
▼
mcp-server/bridge.js ── 一个共享的守护进程；拥有端口 + 扩展程序链接
│ WebSocket
▼
扩展程序服务工作线程
│ chrome.debugger （CDP）+ chrome.tabs / chrome.windows
▼
你的 Chrome 标签页 ──▶ 带到前面，并带有可见光标
```
每个 Claude 应用程序都连接到端口 8765 上一个共享的桥接器守护进程，因此任意数量的应用程序可以共存而不会相互冲突。守护进程在任何 Claude 启动 MCP 服务器时自动启动。
## 快速开始
```bash
git clone https://github.com/am-will/controlium.git
cd controlium
./install.sh
```
安装程序：
1. 安装 MCP 服务器的依赖项，
2. 将 MCP 服务器注册到 **Claude 代码** (`claude mcp add controlium`)，
3. 构建 **Claude 桌面版** 包 (`build/controlium.mcpb`)，
4. 将扩展程序的路径复制到剪贴板并打印一个手动步骤。
然后 **加载扩展程序** （Chrome 不允许脚本执行此操作的唯一操作）：
1. 打开 `chrome://extensions`
2. 启用 **开发者模式** （右上角）
3. 点击 **加载解包扩展程序** 并选择 **`extension/`** 文件夹（已复制到剪贴板）
它显示为 **Controlium** - 连接后，工具栏上的圆点变为绿色。现在可以要求 Claude 控制你的浏览器。
安装程序选项： `./install.sh --code-only`、`--desktop-only`、`--no-desktop`、`--open-desktop` （macOS：还会弹出 Claude 桌面版安装对话框）。
## 手动设置
<details>
<summary><b>Chrome 扩展程序</b></summary>
Chrome 在品牌构建中阻止从命令行加载解包扩展程序，因此请通过 UI 加载它：`chrome://extensions` → **开发者模式** → **加载解包扩展程序** → 选择 `extension/` 文件夹。它在重启后仍然存在。弹出窗口有一个状态圆点和 **bring-to-front** 和 **合成光标** 的切换开关。
</details>
<details>
<summary><b>Claude 代码</b></summary>
```bash
claude mcp add controlium --scope user -- node "$(pwd)/mcp-server/server.js"
```
Claude 代码启动服务器（端口 **8765** 上的桥接器）；扩展程序自动连接。验证使用 `claude mcp list`。
</details>
<details>
<summary><b>Claude 桌面版</b></summary>
最近的 Claude 桌面版构建版本自己管理 `claude_desktop_config.json` 并覆盖手动添加的 `mcpServers`，因此请将其安装为 **桌面扩展程序** （`.mcpb`）：
```bash
./scripts/build-mcpb.sh # 生成 build/controlium.mcpb
open -a Claude build/controlium.mcpb # 打开安装对话框（macOS）
```
或：Claude 桌面版 → **设置 → 扩展程序 → 高级设置 → 安装扩展程序…** → 选择 `build/controlium.mcpb`。（使用 **扩展程序** 部分，*而不是* **连接器** - 连接器仅适用于基于远程 URL 的服务器。）
多个 Claude 桌面版配置文件（例如，一个单独的 "WORK" 安装程序）每个都安装相同的包。所有内容 - Claude 代码和每个桌面版配置文件 - 都共享端口 **8765** 上的一个桥接器守护进程，因此无需管理每个应用程序的端口。同时驱动一个。
</details>
## Claude 可以调用的工具
| 工具 | 描述 |
|------|-------------|
| `list_tabs` | 列出打开的标签页（id、标题、网址、活动、窗口）。 |
| `focus_tab` | **将标签页带到前面** （活动 + 窗口聚焦）。 |
| `new_tab` / `close_tab` | 打开 / 关闭标签页。 |
| `navigate` | 转到网址（或 `back` / `forward`）；等待加载。 |
| `screenshot` | 视口的 PNG（CSS 像素空间；匹配点击坐标）。 |
| `read_page` | 具有 `[ref_N]` 处理程序的无障碍样式大纲。 |
| `get_page_text` | 可见页面文本。 |
| `find` | 按标签查找元素；返回引用 + 坐标。 |
| `click` | 点击坐标或引用（带有可见光标）。 |
| `move_mouse` / `hover` | 移动合成光标 / 触发悬停。 |
| `type_text` | 在页面上输入文本（可选地点击聚焦，然后提交）。 |
| `press_key` | 按键和组合键（`Enter`、`Tab`、`Ctrl+A`、`Meta+L`，...）。 |
| `scroll` | 按方向/数量或 dx/dy 滚动。 |
| `eval_js` | 在页面上运行 JavaScript 并返回结果。 |
| `read_console` / `read_network` | 缓冲的控制台 / 网络活动。 |
| `resize_window` | 调整标签页的 Chrome 窗口大小。 |
每个以标签页为目标的工具都遵循 **bring-to-front** 设置；如果在调用中传递 `focus: false`，则跳过该调用。
## 配置
- **桥接器端口** - 所有内容都共享 `127.0.0.1:8765` 上的一个守护进程。扩展程序的 **桥接器端口** 字段默认为 `8765, 8766, 8767` （额外的条目只是无害地重试）；`8765` 是您需要的全部。如果 8765 被占用，请使用 `CONTROLIUM_PORT` 环境变量覆盖。
- **bring to front** 和 **合成光标** - 弹出窗口/选项中的切换开关，默认为开启。
## 开发
| 路径 | 它是什么 |
|------|-----------|
| `extension/` | MV3 Chrome 扩展程序（服务工作线程，光标叠加层，弹出窗口，选项）。 |
| `mcp-server/` | 节点 MCP 服务器 + localhost WebSocket 桥接器。 |
| `desktop-extension/` + `scripts/build-mcpb.sh` | Claude 桌面版 `.mcpb` 的源代码 + 构建器。 |
| `tests/` | `integration.mjs` （无浏览器）和 `live-e2e.mjs` （真实 Chromium）。 |
| `RESEARCH.md` | 官方扩展程序的工作原理（反向工程）。 |
```bash
npm install # 测试依赖项（ws）
npm test # 协议/桥接器测试 - 无需浏览器
# 完整的浏览器测试需要一个 Chromium，它支持 --load-extension：
npx @puppeteer/browsers install chrome@stable
CHROME_BIN="/path/to/Chrome for Testing" npm run test:live
```
## 注意和限制
- 使用 `chrome.debugger`，因此 Chrome 显示一个 *“… started debugging this browser"* 横幅 - CDP 访问权限的价格，与官方扩展程序相同。
- 只有一个 CDP 客户端可以附加到给定的标签页；如果官方 Claude 扩展程序附加到同一个标签页，请使用不同的标签页（或在那里禁用它）。
- **一次从一个主机驱动**。两个桥接器都可以连接，但同时从 Claude 代码和 Claude 桌面版发出命令会相互冲突，争夺相同的标签页。
- 桥接器（重新）启动后，睡眠的服务工作线程可能需要 ~30 秒才能重新连接；任何浏览器活动都会使其更快恢复。
## 许可证
[MIT](LICENSE)
