tabductor (Ammarbinfaisal)

Tabductor

Use your real Chrome session from any agent that supports local stdio MCP servers.

它的作用

Tabductor将MCP客户端连接到您已经打开的Chrome选项卡。

这意味着您的代理人可以：

• 阅读当前页面
• 查找可点击和可填写的元素
• 单击、键入、导航并等待
• 需要时运行页面本地JavaScript
• 在登录的浏览器配置文件中工作，而不是一次性测试浏览器

它专为可以启动本地stdio MCP服务器的代理而设计。

需求

• 包子
• Chrome或其他可以加载解压缩扩展程序的Chromium浏览器
• 支持本地stdio服务器的MCP客户端

快速开始

1.克隆和构建

git clone https://github.com/ammarbinfaisal/tabductor.git
cd tabductor
bun install
bun run build

构建后，MCP入口点为：

/absolute/path/to/tabductor/dist/index.js

保持这条路。您的MCP客户端将通过stdio运行它。

2.加载扩展

1. 打开 chrome://extensions
2. 启用 Developer mode
3. 点击 Load unpacked
4. 选择回购 extension/ 目录
5. 打开 Tabductor 弹出
6. 确认服务器URL为 ws://127.0.0.1:8765
7. 点击 Connect Active Tab

弹出窗口应显示：

• Active Tab Connected: true
• Socket Status: open

3.将MCP服务器添加到您的代理

如果您的代理支持本地stdio MCP服务器，则通用形状为：

{
  "mcpServers": {
    "tabductor": {
      "command": "bun",
      "args": ["/absolute/path/to/tabductor/dist/index.js"]
    }
  }
}

如果您的客户端有CLI快捷方式，请将其指向相同的位置 dist/index.js 入口点。

法典

codex mcp add tabductor -- bun /absolute/path/to/tabductor/dist/index.js

克劳德代码

claude mcp add -s user tabductor -- bun /absolute/path/to/tabductor/dist/index.js

Gemini CLI

gemini mcp add -s user -t stdio tabductor bun /absolute/path/to/tabductor/dist/index.js

负重力

首选 设置→ MCP服务器 并添加：

{
  "mcpServers": {
    "tabductor": {
      "command": "bun",
      "args": ["/absolute/path/to/tabductor/dist/index.js"]
    }
  }
}

4.可选配置文件

Tabductor还可以从JSON配置文件中读取设置。

在第一次运行时，如果还不存在配置，Tabductor会写入一个默认的全局配置文件 tabductor_new_tab 残疾人。

默认配置加载顺序：

1. 全局用户配置
2. .tabductor.json
3. tabductor.config.json

您还可以使用以下命令指向特定文件 TABDUCTOR_CONFIG.

全局用户配置位置：

• macOS： ~/Library/Application Support/Tabductor/config.json
• Linux： $XDG_CONFIG_HOME/tabductor/config.json 或 ~/.config/tabductor/config.json
• 窗户： %APPDATA%\Tabductor\config.json

例子：

{
  "host": "127.0.0.1",
  "wsPort": 8765,
  "controlPort": 8766,
  "tools": {
    "disabled": ["new_tab"]
  },
  "log": {
    "mode": "errors",
    "dest": "auto",
    "redact": true,
    "include": ["daemon.lifecycle"],
    "exclude": []
  }
}

设置优先级为：

1. 内置默认值
2. 全局配置
3. 项目配置
4. 环境变量

首选环境变量使用 TABDUCTOR_ 前缀，例如：

• TABDUCTOR_HOST
• TABDUCTOR_WS_PORT
• TABDUCTOR_CONTROL_PORT
• TABDUCTOR_LOG_MODE
• TABDUCTOR_LOG_DEST
• TABDUCTOR_LOG_FILE
• TABDUCTOR_ENABLE_TOOLS
• TABDUCTOR_DISABLE_TOOLS

工具名称可以写成短名称，如 navigate 或完整的MCP名称，如 tabductor_navigate.

tabductor_navigate 默认情况下启用。它通过后台服务人员的 chrome.tabs.update({ url }) 因此，它在导航时发生的内容脚本拆卸中幸存下来。仅 http(s) 接受url；延伸起源， chrome://, file://, javascript:, data: 并且在请求到达浏览器之前，类似的方案会因结构化错误而被拒绝。

tabductor_new_tab 默认情况下被禁用，因为它打开了一个用户可能不期望的未跟踪选项卡。通过以下方式显式启用它：

{
  "tools": {
    "enabled": ["new_tab"]
  }
}

5.使用它

一旦代理看到MCP服务器并且扩展已连接，它就可以在当前浏览器选项卡上操作。

交通工具是当地标准。浏览器桥也是本地的。这里没有任何东西需要托管浏览器。

为什么使用它

• 使用您现有的浏览器会话
• 适用于登录状态很重要的网站
• 保持本地执行
• 为代理提供直接的页面交互工具，而无需启动单独的自动化浏览器

代理商如何使用它

选项卡是面向会话的。

每个连接的浏览器选项卡都作为会话公开，代理显式地对该会话进行操作，而不是依赖于隐藏的客户端状态。

这为代理提供了一些有用的属性：

• 它们可以通过使用单独的会话在多个选项卡上并行工作。
• 他们可以通过JavaScript执行工具批量处理页面本地工作，而不是进行许多微小的往返。
• 他们可以在采取行动之前检查页面的紧凑语义快照，这通常比将页面视为原始DOM转储便宜。

在实践中，这意味着代理人可以：

• 在阅读一个会话的同时单击另一个会话
• 按选项卡隔离长时间运行的工作
• 使用快照和引用进行大多数交互
• 使用一步式文本助手进行直接点击和字段输入
• 当需要页面本地过滤、验证或页面逻辑中的多步骤时，可以回退到JS REPL样式的代码段

快照和会话

• 会话是一个已连接选项卡的稳定句柄。
• 快照是为代理使用而构建的页面的紧凑、结构化视图，而不是完全序列化的DOM副本。
• 可操作元素会得到引用，因此代理可以先读取，然后对它发现的确切元素进行操作。
• 页面版本和快照更新有助于代理在页面下方发生更改时进行恢复。

这种模型使多步骤工作流程变得实用，而无需强制代理在每次操作后重新发现整个页面。

备注

• MCP服务器是本地stdio服务器。
• 扩展程序在以下时间与本地守护进程对话 ws://127.0.0.1:8765.
• 多个MCP客户端可以重用同一个本地守护进程。
• 如果重新加载扩展或更改权限，请从弹出窗口重新连接活动选项卡。
• 如果导航出现在瞬态网络错误页面上，则逻辑会话将保留，并在返回到正常可连接页面后重新连接到同一选项卡上。

有待改进的空间

仍然有空间让代理体验更好：

• 围绕JS执行路径进行更丰富的批处理和流处理
• 更好的跨会话编排和调度
• 复杂应用程序上更智能的增量快照更新
• 更广泛的浏览器和客户端设置覆盖范围
• 为那些希望将快速快照读取与偶尔的JS繁重页面逻辑相结合的代理提供更清晰的默认设置

日志记录

当您需要更深入的调试时，可以通过环境变量使用日志控件。

您还可以显式启动守护进程：

mcp-server-tabductor daemon

学分

Tabductor从早期的浏览器控制MCP工作开始，此后围绕其自己的扩展桥、守护进程和面向会话的工具进行了重新设计。

主要的外部影响是：

• 浏览器cp
• 剧作家MCP服务器