Skip to main content
Glama

AgentSurf

License Node.js MCP OAuth 2.0 Browser

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.

AgentSurf live demo: MCP controls a signed-in browser tab with the AI cursor


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


Related MCP server: agent-chrome

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

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:

    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):

    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.

    Getting the AgentSurf extension ID from its Chrome extension card

  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.

    AgentSurf extension panel status

  4. Add the printed MCP config to your agent:

    {
      "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 <token>.

Gemini Web controlling a local Chrome browser over AgentSurf Cloud Gateway (OAuth 2.0 + Reverse WSS)

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:

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.


Licensed under the Apache License 2.0.

Available Tools

29 tools
browser_backbrowser_backB

Go back one entry in the tab history.

Inputs: tab_id (required), session_id, session_name.

browser_claim_tabbrowser_claim_tabA
Idempotent

Take over a tab this session does not own yet, for example a page the user already had open. The tab joins the session group unless you pass group: false, and other sessions are refused it from then on.

Inputs: tab_id (required), group, session_id, session_name.

browser_clickbrowser_clickB

Click an element returned by browser_get_interactives.

Inputs: tab_id (required), element_id (required), frame_id, modifiers, +2 more.

browser_close_tabbrowser_close_tabC
Destructive

Close a Chrome tab.

Inputs: tab_id (required), session_id, session_name.

browser_double_clickbrowser_double_clickB

Double-click an element returned by browser_get_interactives.

Inputs: tab_id (required), element_id (required), frame_id, modifiers, +2 more.

browser_dragbrowser_dragB

Drag one element from browser_get_interactives onto another.

Inputs: tab_id (required), source_element_id (required), target_element_id (required), frame_id, +2 more.

browser_forwardbrowser_forwardB

Go forward one entry in the tab history.

Inputs: tab_id (required), session_id, session_name.

browser_get_framesbrowser_get_framesA
Read-onlyIdempotent

List the frames inside a tab: iframes and blank-src app frames included. Frame 0 is the top document. Pass a returned frame_id to page reads and element actions to work inside that frame.

Inputs: tab_id (required), session_id, session_name.

browser_get_interactivesbrowser_get_interactivesA
Read-onlyIdempotent

List interactive page elements and their opaque element_ids. Call this before any element action. Pass frame_id to inspect an iframe; the top document is frame 0, and an element_id only works in the frame that returned it. A heavy page can hold hundreds of elements, so the list is capped at 150 and reports total plus truncated; narrow it with limit, visible_only, tag, role or name_contains instead of asking for everything.

Inputs: tag, role, limit, tab_id, +5 more.

browser_get_pagebrowser_get_pageC
Read-onlyIdempotent

Read page metadata and viewport state.

Inputs: tab_id, frame_id, session_id, session_name.

browser_get_page_contentbrowser_get_page_contentA
Read-onlyIdempotent

Extract readable page text, and optionally HTML, image, and iframe metadata. Covers the top document unless frame_id targets a frame; app shells keep their real content inside an iframe, so check browser_get_frames when the text looks like navigation only.

Inputs: tab_id (required), frame_id, session_id, include_html, +4 more.

browser_handle_dialogbrowser_handle_dialogA

Accept or dismiss a JavaScript alert, confirm, or prompt. Supply prompt_text when accepting a prompt.

Inputs: action (required), tab_id (required), session_id, prompt_text, +1 more.

browser_list_downloadsbrowser_list_downloadsA
Read-onlyIdempotent

List recent Chrome downloads. Chrome does not record which tab started a download, so tab_id is null unless a previous browser_wait_for_download associated it.

Inputs: tab_id, session_id, session_name.

browser_list_tabsbrowser_list_tabsA
Read-onlyIdempotent

List Chrome tabs without changing the active tab. Start here to find a tab_id. Only this conversation tabs and unclaimed tabs are returned, with other_session_tabs counting what was hidden; pass include_all to see every tab.

Inputs: window_id, session_id, include_all, session_name.

browser_observebrowser_observeB
Read-onlyIdempotent

Capture page state, interactive elements, accessibility data, and a screenshot in one call.

Inputs: tab_id (required), clip, include, full_page, +3 more.

browser_openbrowser_openB

Open a URL in Chrome, or navigate an existing tab when tab_id is given.

Inputs: url (required), tab_id, activate, session_id, +1 more.

browser_pressbrowser_pressC

Press a key on an element returned by browser_get_interactives. Supports optional modifier keys.

Inputs: key (required), tab_id (required), element_id (required), frame_id, +3 more.

browser_reloadbrowser_reloadB

Reload the tab, re-running its scripts.

Inputs: tab_id (required), session_id, session_name.

browser_reset_sessionsbrowser_reset_sessionsA
DestructiveIdempotent

Finish a browser task: release this conversation's session and ungroup its tabs so the group does not linger in the user's tab bar. It also closes the tabs this conversation opened itself, but never a tab the user already had open, so pass close_opened_tabs: false to keep them. force: true instead releases every session, including other conversations', and only ungroups.

Inputs: force, session_id, session_name, close_opened_tabs.

browser_screenshotbrowser_screenshotA
Read-onlyIdempotent

Capture a screenshot of a Chrome tab as an image. Works on a background tab. Prefer this over describing a page in text when layout or visual state matters.

Inputs: tab_id (required), clip, full_page, session_id, +2 more.

browser_scrollbrowser_scrollB

Scroll the document by a pixel delta, reporting whether it reached the top or bottom.

Inputs: tab_id (required), delta_x (required), delta_y (required), session_id, +1 more.

browser_select_optionbrowser_select_optionC
Idempotent

Choose options in a select element by value.

Inputs: tab_id (required), values (required), element_id (required), frame_id, +2 more.

browser_select_textbrowser_select_textC
Idempotent

Select text or place the cursor before or after text in an editable element.

Inputs: tab_id (required), element_id (required), text, frame_id, +3 more.

browser_set_checkedbrowser_set_checkedC
Idempotent

Set a checkbox or radio button to a specific checked state.

Inputs: tab_id (required), checked (required), element_id (required), frame_id, +2 more.

browser_set_filesbrowser_set_filesB

Set files on a file input element using absolute local paths.

Inputs: files (required), tab_id (required), element_id (required), frame_id, +2 more.

browser_switch_tabbrowser_switch_tabA
Idempotent

Bring a tab to the front of its window. Screenshots work without this, but the user will see the tab change.

Inputs: tab_id (required), session_id, session_name.

browser_typebrowser_typeC

Type into an editable element returned by browser_get_interactives.

Inputs: text (required), tab_id (required), element_id (required), frame_id, +2 more.

browser_wait_for_downloadbrowser_wait_for_downloadB
Read-only

Wait for a download to complete or fail, optionally only one started from a given tab.

Inputs: tab_id, session_id, timeout_ms, session_name.

browser_wait_for_elementbrowser_wait_for_elementA
Read-onlyIdempotent

Wait for an element from browser_get_interactives to become attached, detached, visible, or hidden. Get a fresh element_id if the page revision changed while waiting.

Inputs: state (required), tab_id (required), element_id (required), frame_id, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools target clearly distinct browser actions or resources, such as click vs. type vs. drag vs. select_option. The main overlap is browser_observe, which combines page state, interactives, accessibility, and screenshot, potentially competing with browser_get_page, browser_get_interactives, and browser_screenshot, but descriptions clarify when to use each.

    Naming Consistency4/5

    All tools use a consistent browser_ prefix and snake_case, making the set predictable. Most names are verb_noun or verb-only, which is readable, though the mix of patterns is a minor deviation from a strict verb_noun convention.

    Tool Count2/5

    At 29 tools, the surface is heavy for a single server, even for browser automation. Several inspection tools could be consolidated, and the count exceeds the 25-tool threshold where each tool must strongly justify its place.

    Completeness4/5

    The set covers navigation, tabs, frames, element interaction, dialogs, downloads, file inputs, screenshots, and waiting, which is a broad browser-automation lifecycle. Minor gaps remain, such as JavaScript evaluation, hover, and cookie/storage management, but agents can work around most of these.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables remote AI agents to control a local, authenticated desktop browser over MCP through an outbound WebSocket bridge and Chrome extension, supporting tab management, navigation, page reading, clicking, typing, scrolling, screenshots, and JavaScript evaluation.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets local AI agents drive the Chrome browser a user already has open, including signed-in sessions, by listing tabs, reading page text and actionable elements, then clicking, filling, selecting, scrolling, navigating, and capturing viewport screenshots without exporting cookies. Runs as a dependency-free local stdio process over Native Messaging, with per-tab leases, automatic reconnection, and pause/write-action controls.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Lets AI coding tools drive the real, already-logged-in Chrome browser over local stdio—snapshotting and reading pages, clicking, typing, managing tabs, capturing screenshots, and inspecting network, console, storage, and cookies—without opening a remote-debugging port. It installs as a Chrome extension plus native-messaging bridge, so agents work in the user's authenticated sessions while passing bot detection.
      1 npm
      ISC
    • A
      license
      Not graded
      quality
      A
      maintenance
      Lets AI agents control the real, already-logged-in Chrome browser: reading pages, clicking, typing, navigating tabs, taking screenshots, and inspecting cookies, network traffic, console output, and storage. It connects as a local extension over Native Messaging, so no remote-debugging port or headless profile is needed.
      1 npm
      ISC