Chrome Extension MCP Bridge

Chrome扩展程序MCP桥

AI代理通过MCP协议+Chrome扩展+WebSocket桥控制Chrome浏览器

建筑

[AI Agent]
    ⇅ (MCP Tools via stdio)
[Node.js App — MCP Server + WebSocket Server]
    ⇅ (WebSocket on port 7890)
[Chrome Extension (Manifest V3)]
    ⇅ (chrome.* APIs)
[Browser Tabs]

运作原理

1. AI 代理 调用MCP工具（例如。， capture_screenshot, execute_js)通过MCP协议（stdio传输）
2. Node.js服务器 接收MCP工具调用，生成 requestId，并通过WebSocket向Chrome扩展程序发送JSON命令
3. Chrome 扩展 （service worker）接收命令，使用Chrome API执行浏览器操作，并返回具有相同内容的JSON响应 requestId
4. Node.js服务器 解析待定的Promise并将结果返回给AI代理

______________________________________________________________________

项目结构

/chrome-extension-mcp
├── extension/                  # Chrome Extension (Manifest V3)
│   ├── manifest.json           # Extension manifest
│   ├── background.js           # Service worker — WS client + action handlers
│   └── content.js              # Content script (placeholder)
├── server/                     # Node.js backend
│   ├── index.js                # Entry point — starts WS + MCP servers
│   ├── wsServer.js             # WebSocket server — client management + command dispatch
│   ├── mcpServer.js            # MCP server — tool registration via @modelcontextprotocol/sdk
│   ├── cli.js                  # CLI tool for testing commands
│   ├── tools/                  # MCP tool definitions
│   │   ├── captureScreenshot.js
│   │   ├── getHtml.js
│   │   ├── executeJs.js
│   │   ├── openTab.js
│   │   ├── listTabs.js
│   │   └── closeTab.js
│   └── package.json            # Server dependencies
├── package.json                # Root scripts
└── README.md                   # This file

______________________________________________________________________

MCP工具

其他扩展操作（可通过CLI/Webocket获得）

______________________________________________________________________

通信协议

请求（服务器→ 扩展）

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "action": "capture_screenshot",
  "payload": {
    "tabId": 123
  }
}

响应（扩展→ 服务器）

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "success": true,
  "data": {
    "tabId": 123,
    "format": "png",
    "base64": "iVBORw0KGgo..."
  },
  "error": null
}

错误响应

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "success": false,
  "data": null,
  "error": "No active tab found"
}

______________________________________________________________________

安装说明

先决条件

• Node.js v18+（建议使用LTS）
• 谷歌浏览器 浏览器
• npm 包管理器

1.安装服务器依赖关系

cd server
npm install

或者从项目根目录：

npm run install:server

2.启动Node.js服务器

服务器同时运行两个组件：

• WebSocket服务器 在港口 7890 （可通过以下方式配置 WS_PORT 任何人）
• MCP服务器 在stdio上（用于AI代理通信）

cd server
node index.js

或者从项目根目录：

npm start

您应该看到：

[WS] WebSocket server attached to HTTP server
[Server] HTTP + WebSocket server listening on port 7890
[MCP] Server started on stdio transport

3.加载Chrome扩展程序

1. 打开Chrome浏览器并导航到 chrome://extensions/
2. 启用 开发人员模式 （在右上角切换）
3. 点击 “未包装装载”
4. 选择 extension/ 此项目中的文件夹
5. 扩展将加载并自动连接到WebSocket服务器

您可以验证连接：

• 打开扩展的服务工作者控制台（在扩展页面上单击“检查视图：服务工作者”）
• 您应该看到： [MCP Extension] Connected to server

4.验证健康检查

curl http://localhost:7890/health

预期响应：

{
  "status": "ok",
  "connectedClients": 1,
  "clients": [""]
}

______________________________________________________________________

测试MCP工具

使用CLI工具

CLI工具直接连接到WebSocket服务器，并向扩展发送命令。

单命令模式

# List all open tabs
cd server
node cli.js list_tabs

# Open a new tab
node cli.js open_tab '{"url":"https://www.google.com"}'

# Capture screenshot of active tab
node cli.js capture_screenshot

# Capture screenshot by tab title
node cli.js capture_screenshot '{"title":"Google"}'

# Get HTML of active tab
node cli.js get_html

# Execute JavaScript
node cli.js execute_js '{"script":"return document.title"}'

# Close a tab (use tabId from list_tabs)
node cli.js close_tab '{"tabId":123}'

# Get visible text
node cli.js get_text

# Get element by selector
node cli.js get_element '{"selector":"h1"}'

交互模式

cd server
node cli.js

这将启动一个REPL，您可以在其中键入命令：

mcp> list_tabs
mcp> open_tab {"url":"https://github.com"}
mcp> capture_screenshot {"title":"GitHub"}
mcp> execute_js {"script":"return document.title"}
mcp> exit

与AI代理（MCP客户端）一起使用

配置您的MCP客户端（例如，Claude Desktop、Cursor等）以使用此服务器：

Claude桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "chrome-browser": {
      "command": "node",
      "args": ["/absolute/path/to/chrome-extension-mcp/server/index.js"],
      "env": {
        "WS_PORT": "7890"
      }
    }
  }
}

光标配置

添加到您的 .cursor/mcp.json:

{
  "mcpServers": {
    "chrome-browser": {
      "command": "node",
      "args": ["/absolute/path/to/chrome-extension-mcp/server/index.js"],
      "env": {
        "WS_PORT": "7890"
      }
    }
  }
}

配置后，AI Agent将可以访问所有6个MCP工具来控制您的Chrome浏览器。

______________________________________________________________________

配置

环境变量

扩展设置

WebSocket URL是硬编码的 extension/background.js:

const WS_URL = 'ws://localhost:7890';

如果您的服务器在其他主机/端口上运行，请更改此设置。

______________________________________________________________________

安全考虑

1. 默认情况下仅限本地：WebSocket服务器绑定到 localhost。该扩展仅连接到 localhost.
2. 没有明确的工具调用，就无法执行任意代码：The execute_js 工具需要明确的 script 参数——如果没有正确的请求，扩展将不会执行代码。
3. 请求-响应相关性：每个命令都使用一个唯一的 requestId （UUID v4）以防止响应欺骗。
4. 超时保护：命令在30秒后超时，以防止挂起。
5. 客户端标识：每个扩展都用一个唯一的标识来标识自己 clientId 连接。

生产建议

• 向WebSocket连接添加身份验证令牌
• 限制 execute_js 进入允许脚本的白名单
• 使用带有TLS证书的WSS（WebSocket安全）
• 添加速率限制以防止滥用

______________________________________________________________________

错误处理

服务器端

• 未连接客户端：退货 "No Chrome extension clients connected"
• 请求超时：退货 "Request timed out after 30000ms"
• 发送失败：退货 "Failed to send command: ..."

延伸侧

• 未知动作：退货 "Unknown action: "
• 缺少必填字段：退货 "Missing required field: "
• 未找到选项卡：退货 "No tab found matching title: "
• 脚本执行错误：从页面上下文返回错误消息

______________________________________________________________________

发展

调试扩展

1. 首选 chrome://extensions/
2. 查找“Chrome扩展程序MCP桥”
3. 点击 “检查视图：服务人员” 打开DevTools
4. 所有日志都以前缀 [MCP Extension]

调试服务器

所有服务器日志都转到 stderr （因此它们不会干扰MCP stdio通信）：

• [WS] --WebSocket服务器事件
• [MCP] --MCP服务器事件
• [Server] --常规服务器事件

添加新工具

1. 在中创建新文件 server/tools/ 遵循现有模式
2. 导出一个工厂函数，该函数需要 wsServer 并返回 { name, description, inputSchema, handler }
3. 导入并注册 server/mcpServer.js
4. 在中添加相应的操作处理程序 extension/background.js

______________________________________________________________________

故障排除

______________________________________________________________________

许可证

麻省理工学院