Sansan Chrome MCP

通过 MCP (Model Context Protocol) 让 AI 助手控制你的 Chrome 浏览器。

工作原理

┌──────────────┐     HTTP/SSE      ┌──────────────────┐    Native Messaging    ┌──────────────────┐
│  AI 助手      │ ◄──────────────► │  Native Server    │ ◄──────────────────►  │  Chrome 扩展      │
│  Claude/等    │   localhost:2733  │  sansan-chrome-   │   com.sansan.chrome   │  Sansan Chrome MCP│
└──────────────┘                   │  bridge           │                      └──────────────────┘
                                   └──────────────────┘

AI 助手通过 MCP 协议调用工具 → Native Server 转发请求 → Chrome 扩展执行浏览器操作 → 返回结果。

快速开始

1. 安装 Native Server

npm install -g sansan-chrome-bridge

安装后 postinstall 会自动注册 Native Messaging host。如注册失败,可手动执行:

sansan-chrome-bridge register       # 用户级注册(推荐)
sansan-chrome-bridge register --system  # 系统级注册(需管理员权限)

2. 安装 Chrome 扩展

1. 下载最新的 sansan-chrome-mcp.zip (或从源码构建,见下方)
2. 解压后在 Chrome 中打开 chrome://extensions/
3. 开启「开发者模式」→ 点击「加载已解压的扩展程序」→ 选择解压目录

3. 配置 AI 客户端

Claude Code / kscc:

在 MCP 配置文件中添加:

{
  "mcpServers": {
    "chrome": {
      "url": "http://127.0.0.1:2733/mcp"
    }
  }
}

Stdio 方式(备选):

{
  "mcpServers": {
    "chrome": {
      "command": "sansan-chrome-stdio"
    }
  }
}

4. 验证

sansan-chrome-bridge doctor

该命令会自动检测安装状态、注册表、扩展连接等,并给出修复建议。

支持的工具

工具	说明
browser_get_windows_and_tabs	获取所有窗口和标签页信息
browser_read_page	读取页面内容
browser_computer	鼠标/键盘操控(点击、滚动、输入等)
browser_navigate	导航到指定 URL
browser_screenshot	页面截图
browser_close_tabs	关闭标签页
browser_switch_tab	切换标签页
browser_web_fetcher	抓取网页内容
browser_network_request	发送网络请求(携带浏览器 Cookie)
browser_network_capture	捕获网络请求/响应
browser_handle_download	处理浏览器下载
browser_history	搜索浏览历史
browser_bookmark_search	搜索书签
browser_bookmark_add	添加书签
browser_bookmark_delete	删除书签
browser_javascript	在页面中执行 JavaScript
browser_click	点击页面元素
browser_fill	填写表单
browser_request_element_selection	请求用户手动选择元素
browser_keyboard	模拟键盘输入
browser_console	捕获控制台输出
browser_file_upload	上传文件
browser_handle_dialog	处理浏览器对话框(alert/confirm/prompt)

CLI 命令

sansan-chrome-bridge register [--system]    # 注册 Native Messaging host
sansan-chrome-bridge fix-permissions        # 修复执行权限
sansan-chrome-bridge update-port <port>     # 更新 stdio 模式端口
sansan-chrome-bridge doctor [--fix]         # 诊断安装问题(可选自动修复)
sansan-chrome-bridge report                 # 导出诊断报告(用于提交 Issue)

从源码构建

环境要求

• Node.js >= 20
• pnpm >= 10

构建

git clone https://github.com/yourname/chrome-mcp.git
cd chrome-mcp

pnpm install
pnpm build

开发

# 同时启动 shared + native-server + extension 开发模式
pnpm dev

打包扩展

cd app/chrome-extension
pnpm zip
# 产物在 .output/ 目录下

项目结构

chrome-mcp/
├── packages/
│   └── shared/              # 共享类型、工具定义、常量
│       └── src/
│           ├── constants.ts # HOST_NAME、默认端口等
│           ├── types.ts     # 消息类型、工具类型
│           └── tools.ts     # 所有 MCP 工具 schema
├── app/
│   ├── native-server/       # Native Messaging host (npm: sansan-chrome-bridge)
│   │   └── src/
│   │       ├── cli.ts       # CLI 入口
│   │       ├── mcp/         # MCP Server 实现
│   │       ├── server/      # Fastify HTTP 服务
│   │       ├── native-messaging-host.ts  # Chrome Native Messaging 通信
│   │       └── scripts/     # 注册、诊断、构建脚本
│   └── chrome-extension/    # Chrome 扩展 (Vue 3 + WXT)
│       └── src/
│           ├── entrypoints/ # background、popup、content scripts
│           ├── common/      # 通用工具
│           └── inject-scripts/ # 注入页面的脚本
├── pnpm-workspace.yaml
└── package.json

发布

详见 docs/PUBLISHING.md

故障排除

运行诊断工具:

sansan-chrome-bridge doctor

常见问题:

问题	解决方案
Permission denied / Native host has exited	sansan-chrome-bridge fix-permissions
Windows 注册表未写入	以管理员身份运行 sansan-chrome-bridge register
扩展无法连接	确认扩展已安装且 Chrome 已重启
端口冲突	sansan-chrome-bridge update-port <新端口>

更多排查步骤见 app/native-server/install.md

致谢

本项目基于 mcp-chrome 修改而来，感谢原作者 @hangwin 的工作。

License

MIT