AgentSurf

MCP开发工具

提供方 未标注

开发工具 Streamable HTTP OAuth 授权 社区 / 第三方 Claude DesktopClaudeCursorVS Code

让本地(stdio)和远程(Streamable HTTP + OAuth 2.0)AI 智能体控制你已打开的、已登录的 Chrome/Edge 浏览器,支持多台电脑的窗口路由,并默认采用只读的远程设置。 浏览适用于 Claude、Cursor、VS Code 等 AI 智能体的 AgentSurf MCP...

一句话选型结论

按资料字段整理

AgentSurf 属于开发工具类 MCP 服务器,Streamable HTTP,OAuth 授权,可直接接入 Claude Desktop、Claude、Cursor 等,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式Streamable HTTP 鉴权OAuth 授权 部署方式支持远程部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

开发

安装与配置

Streamable HTTP OAuth 授权
新一代远程传输,替代 SSE
  1. 1
    准备运行环境

    确认你的客户端支持远程端点,并拿到服务地址。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • 远程端点依赖网络与服务方可用性,注意密钥与调用额度。
  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
AgentSurf当前 未标注 Streamable HTTP 支持远程部署 无 2026-11-20
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类开发工具本站按上游分类展示
连接方式Streamable HTTP新一代远程传输,替代 SSE
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型支持远程部署上游给出的部署形态
最近核验2026-11-20上游最后核验时间

详细介绍

11.5 KB
来自项目仓库与上游目录的原文,未做删改

AgentSurf

English | 简体中文

Give any AI agent — local or cloud — safe control over the Chrome or Edge browser you are already signed into.

AgentSurf connects Claude Desktop, Cursor, Codex, Gemini Web, Notion AI, Dify, and any MCP-compatible agent to your real desktop browser. It reuses your existing logins and open tabs without launching headless browsers, exporting cookies, or triggering bot-detection walls.


Why AgentSurf?

If you are choosing between Playwright / Puppeteer MCP, local shell browser skills like Tencent BrowserSkill (bsk), and AgentSurf, here is why users pick AgentSurf:

  • Works with Cloud & Web AI — Not Just Local Terminals: Local CLI skills (like BrowserSkill) require an agent with local bash/shell access, and Playwright MCP launches isolated local sandboxes. AgentSurf exposes standard MCP (stdio + Streamable HTTP) with built-in OAuth 2.0 (PKCE) so Gemini Web, Notion AI, Dify, and mobile/cloud workflows can drive your real desktop browser with zero local shell permission required.
  • Home + Office Multi-PC on One Gateway: Instead of one daemon bound to one machine, both your home and office browsers connect to the same wss://.../ws endpoint without kicking each other offline—automatically routing to whichever Chrome window you are actively using.
  • No Shell Execution Risk & Built for Token Efficiency: Unlike CLI-driven browser skills, your agent never needs shell access to control the browser. Interactive snapshots are filtered and capped inside the page before crossing the wire—on a reference 665-element app page (245 KB raw JSON), the default 150-element cap cuts output from ~66,800 to ~15,100 tokens, and filtering hidden UI (visible_only: true) or querying by tag / role / name_contains shrinks it further depending on visible page density.
  • Self-Hosted Privacy & Zero Lock-In: No third-party cloud relay, no telemetry, and no account required. Run 100% offline locally or self-host the single-file standalone-gateway.js (read-only by default on remote, hashed tokens, SHA-256 operation idempotency journal, and zero MAIN-world console patching).
Capability AgentSurf Local Shell Browser Skills (e.g. Tencent BrowserSkill) Headless MCP (Playwright / Puppeteer)
Reuses signed-in Chrome / Edge Yes (live tabs & cookies) Yes (live browser via extension) No (starts fresh or needs brittle profile copies)
Anti-bot friendliness Real desktop browser session Real desktop browser session Often flagged by headless automation signals
Agent protocol Standard MCP (stdio + Streamable HTTP) — no shell required Local CLI (bsk) — requires shell-capable coding agent Local stdio / local server MCP
Cloud Web Agents (Gemini Web, Notion AI, Dify) Built-in OAuth 2.0 (PKCE) + Bearer + Reverse WSS Local shell agents only Local only unless custom-wrapped
Home + Office multi-PC routing Yes — active-window auto-routing, session stickiness & pinning Single local machine daemon Single local process
Context & token footprint In-page filtering (visible_only, tag, role, name_contains) + 150-element cap Page extraction via CLI commands Large raw DOM / AX tree dumps
Safety & isolation Remote read-only default, per-session Tab Groups, operation_unknown idempotency, zero MAIN-world patching Dedicated agent window / tab borrowing + human confirmation Shared browser state; full read/write by default

Key Features

  • Dual-Channel Transport:
  • Local Native (stdio): Zero network dependencies, ultra-low latency via Chrome Native Messaging + loopback bridge (127.0.0.1:8765).
  • Cloud Remote Gateway (Streamable HTTP + Reverse WSS): Deploy a single self-contained standalone-gateway.js on any VPS. Your local browser initiates an outbound encrypted WebSocket connection—no port forwarding, SSH tunnels, or public IP needed on your PC.
  • Full OAuth 2.0 + PKCE & Bearer Token Support:
  • Implements MCP OAuth discovery (/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server), Client ID / Client Secret, S256 PKCE, consent UI, and refresh tokens—ready for Gemini Web.
  • Also supports static Bearer Token headers for Notion AI, Dify, and custom HTTP MCP agents.
  • Port-Agnostic Public Routing:
  • Host, Origin, and OAuth metadata adapt dynamically to the incoming request Host and X-Forwarded-Proto, so one gateway config works across standard port 443 or any alternate reverse-proxy port.
  • Multi-Computer Coexistence (Home + Office):
  • Connect multiple computers (e.g., Home and Office) to the same wss://.../ws endpoint without kicking each other offline.
  • Routes automatically to whichever Chrome window you actively focused/used most recently, locks active sessions to their originating computer, and supports pinning in the extension popup or explicit device targeting.
  • 29 Browser Control Tools (Token-Efficient by Design):
  • Semantic interactive element snapshots (browser_get_interactives with opaque element_ids, in-page filtering by tag / role / name_contains / visible_only, and default 150 cap—trimming a 245 KB / 665-element raw snapshot to 150 elements by default, and much smaller when scoped to visible or matching controls).
  • Page content extraction, click/double-click/type/press/select/checkbox/drag/scroll, viewport & full-page screenshots, iframe navigation, JS dialog handling, downloads, and file uploads (DOM.setFileInputFiles).

Architecture```mermaid

flowchart LR
subgraph Local["Local Mode (Zero Network)"]
LAgent["Claude Desktop / Cursor / Codex"] -->|stdio MCP| LServer["agentsurf-mcp"]
LServer -->|Local WS| NHost["Native Messaging Host"]
NHost -->|Native Messaging| Ext["AgentSurf Extension (Chrome / Edge)"]
end

subgraph Cloud["Cloud Mode (OAuth 2.0 + Reverse WSS)"]
CAgent["Gemini Web (OAuth 2.0) / Notion AI / Dify"] -->|HTTPS Streamable MCP| Proxy["Caddy / Nginx HTTPS"]
Proxy --> GW["standalone-gateway.js (:8767)"]
HomeExt["Home Chrome Extension"] -->|Outbound WSS| GW
WorkExt["Office Chrome Extension"] -->|Outbound WSS| GW
end


---

## Quick Start

### Prerequisites

| Requirement | Version & Check |
| --- | --- |
| **Node.js** | `20+` (`node -v`) |
| **Git** | `git --version` |
| **Chrome or Edge** | `116+` (`chrome://version` / `edge://version`) |

> No administrator privileges required. Your existing browser profiles, passwords, and settings are never modified.

---

### Path A: Local Deployment (Claude Desktop, Cursor, Codex, etc.)

1. **Clone and run the setup wizard**:```bash
   git clone https://github.com/ztao0916/agentsurf-browser-control-runtime.git
   cd agentsurf-browser-control-runtime
   npm run setup
   ```

   To configure **both** Chrome and Edge simultaneously (with separate ports and configs):```bash
   npm run setup -- --browser all
   ```

2. **Load the extension in Chrome / Edge**:
   - Open `chrome://extensions` (or `edge://extensions`) and enable **Developer mode**.
   - Click **Load unpacked** and select the project's `dist/` folder.
   - Copy the generated **Extension ID** from the AgentSurf card and paste it into the terminal prompt.

3. **Reload & verify the extension popup**:
   - Click **Reload** on the AgentSurf extension card, then click the AgentSurf toolbar icon and verify **Local Native** is active.

4. **Add the printed MCP config to your agent**:```json
   {
     "mcpServers": {
       "agentsurf": {
         "command": "<absolute launcher path printed by setup>"
       }
     }
   }
   ```

   When installed with `--browser all`, `setup` prints separate `agentsurf-chrome` and `agentsurf-edge` entries so you can target either browser cleanly.

---

### Path B: Remote Cloud Gateway (Gemini Web, Notion AI, Dify, Remote Agents)

Use Remote Gateway mode when your AI runs in the cloud and needs to control your local browser over HTTPS/WSS.

1. Build the single-file gateway locally (`npm run build` produces `dist/mcp/standalone-gateway.js` with zero `node_modules` needed on the server).
2. Upload `dist/mcp/standalone-gateway.js` to your server behind Caddy/Nginx HTTPS, initialize credentials (`init-remote --url https://mcp.example.com`), and start it with PM2 (`start-remote`).
3. Pair your Chrome/Edge extension in the popup under **Remote Gateway** using your `wss://.../ws` URL, Pairing Token, and an optional **Device Name** (e.g., `Home` / `Office`).
4. Connect your cloud client:
   - **Gemini Web**: Use the generated `OAuth Client ID` and `OAuth Client Secret`, register Gemini's Redirect URI with `add-oauth-redirect --uri "..."`, and approve the browser prompt with your Pairing Token.
   - **Notion AI / Dify / Custom HTTP MCP**: Use `https://mcp.example.com/mcp` with `Authorization: Bearer `.

> **Note on Gemini Web confirmations**: The demo GIF above trims out waiting spinners and permission cards for brevity. AgentSurf marks read-only inspection tools with MCP `readOnlyHint: true` (which Gemini groups under **Read** and allows automatically), while **Gemini Web's client-side security policy still prompts you to click `Always allow` on interactive / state-changing tools** (`browser_start_session`, `browser_open`, `browser_type`, `browser_click`, `browser_scroll`, `browser_end_session`, etc.)—even if **Write / delete** is already set to `Always allow` in **App actions**.

👉 **Full step-by-step instructions**: **Remote Gateway & OAuth 2.0 Guide (docs/remote-gateway.en.md)**

---

## Multi-Browser & Multi-Computer Routing

### Multiple browsers on one PC (Chrome + Edge)
Each MCP server entry (`agentsurf` / `agentsurf-chrome` vs `agentsurf-edge`) runs its own isolated bridge, tab leases, and sessions. Do not pass a Chrome `tab_id` or `element_id` to the Edge server.

### Multiple PCs on one Cloud Gateway (Home + Office)
1. Connect both browsers to the same `wss://mcp.example.com/ws` URL with the same Pairing Token and distinct **Device Names** (e.g., `Home`, `Office`).
2. **Automatic active routing**: The gateway defaults to whichever computer's Chrome window was most recently focused or used by you—idle/background browsers reconnecting will not steal control.
3. **Session stickiness**: Once `browser_start_session` starts on a computer, every step of that task stays pinned to that same computer until completion.
4. **Manual control when needed**: Click **Pin as active** in the extension popup to lock a browser, pass `device: "Office"` to `browser_start_session`, or connect via `https://mcp.example.com/mcp?device=Home`.

---

## Use and verify

Ask your connected agent:```text
Open https://example.com and tell me the page title.

> Seeing "Chrome is being debugged" during screenshots or file uploads is normal Chrome CDP behavior.

Safety Recommendations

  • Start in read-only mode when deploying the remote gateway (init-remote defaults to read-only; explicitly switch to interactive only when ready).
  • Keep human confirmation before consequential actions such as submitting forms, making purchases, deleting records, uploading files, or sending messages.
  • Never share secrets (passwords, OTPs, cookies, or pairing tokens) inside prompts, and never commit local config.json or remote-config.json files.

Documentation & Links

  • Remote Gateway Deployment & OAuth 2.0 Guide (中文版)
  • Developer & Protocol Reference (中文版)
  • Security Policy
  • Contributing
  • Changelog

Licensed under the Apache License 2.0.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
AgentSurf 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

AgentSurf 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是Streamable HTTP,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

AgentSurf 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

AgentSurf 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

AgentSurf 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Gemini CLI、Codex;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

AgentSurf 能提供哪些能力?

资料显示能力标签包括 开发。具体工具清单以官方文档为准。

AgentSurf 需要什么运行环境?

属于远程端点,不需要在本地装运行时。

AgentSurf 是本地还是远程?

它是远程端点,连服务地址即可。传输方式为Streamable HTTP。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-11-20。