# Surf CLI — Control Chrome for AI Agents (No MCP)

> Surf CLI lets agents control Chrome via a local extension + native host, offering agent-agnostic browser control without running an MCP server.

## Install

Copy the content below into your project:

## Quick Use

1. Install globally:
   ```bash
   npm install -g surf-cli
   ```
2. Load the extension in Chrome (per README):
   - open `chrome://extensions`, enable Developer mode
   - click “Load unpacked” and paste the path from `surf extension-path`
3. Install the native host (copy extension ID from `chrome://extensions`):
   ```bash
   surf install <extension-id>
   ```
4. Restart Chrome and test:
   ```bash
   surf tab.list
   ```

## Intro

Surf CLI lets agents control Chrome via a local extension + native host, offering agent-agnostic browser control without running an MCP server.

- **Best for:** agents that need real browser state (cookies, tabs) and teams who want local-only browser control without extra servers
- **Works with:** Node.js + Chrome extension workflow, native host install via `surf install`, multi-browser flags documented (brave/edge/arc etc.)
- **Setup time:** 15–25 minutes

## Practical Notes

- README quick start is a 4-step install: npm global install, load unpacked extension, `surf install <extension-id>`, then `surf tab.list`.
- README lists supported browsers: chrome, chromium, brave, edge, arc, helium (plus `--browser all`).

## A Safe Integration Pattern for Agents

Browser control becomes risky when agents can navigate and click freely. Practical guardrails:

- Give the agent a “read-only” browsing phase first: list tabs, capture URLs, extract text.
- Use explicit allowlists for domains your agent is allowed to interact with.
- Treat extension/native host changes like code: update via PRs, not ad-hoc local edits.

## Troubleshooting Checklist

- If the extension path changes, re-run `surf extension-path` and reload unpacked extension.
- If a package manager stores binaries in non-standard locations, the README documents env vars such as `SURF_NODE_PATH` / `SURF_HOST_PATH` / `SURF_EXTENSION_PATH`.


### FAQ

**Q: Is this MCP-based?**
A: The README positions Surf as a CLI + extension/native host flow; it emphasizes zero MCP server configuration.

**Q: What’s the hardest step?**
A: Typically loading the unpacked extension and copying the extension ID for `surf install`.

**Q: Can I use other browsers?**
A: Yes—README lists multiple browsers and shows `--browser` flags, including `--browser all`.

## Source & Thanks

> Source: https://github.com/nicobailon/surf-cli
> License: MIT
> GitHub stars: 477 · forks: 43

---

<!-- ZH -->

## 快速使用

1. 全局安装：
   ```bash
   npm install -g surf-cli
   ```
2. 按 README 加载 Chrome 扩展：
   - 打开 `chrome://extensions`，开启 Developer mode
   - 点 “Load unpacked”，路径来自 `surf extension-path`
3. 安装 native host（extension id 从 `chrome://extensions` 复制）：
   ```bash
   surf install <extension-id>
   ```
4. 重启 Chrome 测试：
   ```bash
   surf tab.list
   ```

## 简介

Surf CLI 通过“本地扩展 + native host”让 AI Agent 控制 Chrome：零配置、agent-agnostic，不需要单独起 MCP server，适合把浏览器当作通用工具接口。

- **适合谁：** 需要真实浏览器状态（cookies、tabs）的 Agent，以及想要本地控制、不额外起服务的团队
- **可搭配：** Node.js + Chrome 扩展流程、通过 `surf install` 安装 native host、README 描述多浏览器支持（brave/edge/arc 等）
- **准备时间：** 15–25 分钟

## 实战建议

- README Quick Start 是 4 步：npm 全局安装、加载 unpacked 扩展、`surf install <extension-id>`、最后 `surf tab.list` 测试。
- README 列出支持浏览器：chrome、chromium、brave、edge、arc、helium，并提供 `--browser all`。

## Agent 集成的安全姿势

浏览器控制的风险在于“可导航、可点击、可带 cookies”。务实护栏：

- 先让 Agent 进入“只读阶段”：列出 tabs、收集 URL、提取文本。
- 对可交互域名做 allowlist，避免无意跳转到不可信站点。
- 扩展与 native host 的更新要走 PR/审核，不要临时在本机随手改。

## 排障清单

- 扩展路径变化时，重新执行 `surf extension-path` 并重新加载 unpacked extension。
- 包管理器导致二进制路径不标准时，README 给出 `SURF_NODE_PATH` / `SURF_HOST_PATH` / `SURF_EXTENSION_PATH` 等环境变量配置方式。


### FAQ

**这是 MCP 方案吗？**
答：README 将 Surf 定位为 CLI + 扩展/native host 流程，并强调无需配置 MCP server。

**最容易卡在哪一步？**
答：通常是加载 unpacked 扩展，以及复制 extension id 用于 `surf install`。

**能用其它浏览器吗？**
答：可以。README 列出多浏览器并提供 `--browser` 参数（包含 `--browser all`）。

## 来源与感谢

> Source: https://github.com/nicobailon/surf-cli
> License: MIT
> GitHub stars: 477 · forks: 43


---
Source: https://tokrepo.com/en/workflows/surf-cli-control-chrome-for-ai-agents-no-mcp
Author: Script Depot