Duplex MCP server
Commit Nov 15, 2026A collaborative desktop browser that allows humans and AI to share the same tabs, sessions, and live web interactions simultaneously.
Also known as Eric-huang799/duplex
- Stars
- 9
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is Duplex MCP?
Duplex is a collaborative desktop browser that allows humans and AI to share the same tabs, sessions, and live web interactions simultaneously. It exposes 8 tools, such as snapshot, screenshot, drag.
Summary generated from the project's README
About Duplex MCP server
Collaborating with an AI on live web tasks is what Duplex enables through a shared desktop browser environment. Unlike hidden automation tools, this browser allows humans and AI to occupy the same tabs and active sessions simultaneously. You see the rendered page while the AI reads the DOM, source code, and screenshots to perform actions like clicking or typing.
Users can connect various agents including a built-in model via OpenAI-compatible providers like Ollama or DeepSeek, as well as external tools like Claude Code, Codex, and opencode. The server uses a panel-scoped model where browser control is only granted when an agent is launched or resumed from the Duplex interface. This ensures that standalone terminal sessions do not unexpectedly control your browser.
Security is managed through explicit governance, requiring user consent for sensitive sites and allowing permissions to be revoked per origin. The system includes 25 specialized browser tools, such as snapshotting pages into DOM outlines, and features an emergency stop command to immediately abort all running tool calls.
What you can do with it
- 1Co-browsing for web tasksA developer can work alongside an AI in the same logged-in session to navigate websites together.
- 2Visualizing AI interactionsUsers can monitor exactly where an AI is clicking or typing through visual highlights and a cursor ring.
- 3Annotating web elementsYou can draw shapes on a webpage to provide structured instructions to the AI agent.
- 4Connecting external CLI agentsDevelopers can mirror Claude Code or Codex sessions directly within the browser panel.
Written from the project's README. Every use case is checked against a quote from it.
Duplex MCP tools 8
Detected from the READMEsnapshotscreenshotdragscrollwaitget_consoleannotation_modeevaluate
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableeric-huang799/duplex is public and reachablegithub.com/eric-huang799/duplex ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/eric-huang799/duplex ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubDuplex
Listed in awesome-mcp-servers · awesome-mcp-list · TensorBlock · Awesome-MCP-ZH · freemcp.space · Glama
One browser shared by a human and an AI. You see the rendered page; the AI reads the DOM, source and screenshots and can act through browser tools. Same tabs, same live session, at the same time.
English | 中文

Duplex start page (light theme). A dark theme is also included.
Demo
Full demo — 2 min, with captions and music:
One continuous walkthrough: the AI opens the first website ever published, plays a Bilibili video, clears a Minesweeper board, writes a sentence in Microsoft Word for the web, and shows bookmarks already on the PC — while the side panel mirrors every decision and the browser stays visible.

A harder, unscripted test: with no spreadsheet-specific skill installed, the built-in model used the stock API and a few simple automation skills to push a whole grade sheet into Excel for the web. It worked, but it was slow and token-heavy — a feasibility demo, not a recommended workflow. The screenshot shows the resulting sheet in the current UI.
0.3.0-beta.1: the governance release
0.3.0-beta.1 makes the boundary between an AI and your browser explicit and enforced: sensitive sites require your consent before the agent may enter, site permissions are revocable per origin, and the agent stops when a page asks for human verification instead of trying to get past it.
Highlights: reads and clicks/typing moved in-process (no DevTools attachment needed for the action itself), ad blocking with EasyList rules actually injected, page DevTools (F12), printing and Save as PDF, spellcheck suggestions, ten preset tasks, chat export to Markdown, and a browser settings panel that also rolls back agent-made changes.
Previous: 0.2.10 introduced the panel-scoped agent model — an agent gets browser control only when you start or continue it from Duplex. Nothing is installed globally behind your back.
- Bilingual interface — the renderer, native menus, context menus, dialogs and the annotation overlay switch between Simplified Chinese and English. Follow the system locale or pin a language from the tools menu.
- In-app search-engine menu — the address-bar engine picker is a themed in-app dropdown for Baidu, Bing and Google; it no longer depends on a native popup menu.
- Panel-scoped browser control — Codex, Claude Code and opencode receive Duplex's MCP browser tools only for prompts issued from the panel. Standalone sessions do not get browser control. opencode gets a dedicated
duplexagent; normal opencode sessions denyduplex_*by default.
| Agent | Conversation in the panel | Browser control from the panel | Continue from the panel |
|---|---|---|---|
| Built-in model | Live stream | Built-in browser tools | Session history |
| opencode | Live text + tool calls | duplex agent, duplex_* allowed |
Panel message or plugin |
| Codex | Local transcript | MCP injected for each panel launch/resume | codex exec resume |
| Claude Code | Local transcript | MCP via --mcp-config for each panel launch/resume |
claude --resume |
| Gemini / Qwen / custom | Transcript / stream | Depends on the CLI's own tools | CLI-specific |
Why Duplex
Most AI browsing tools fall into one of two camps:
- Separate automation instances run a hidden browser. You cannot see the page, use the same login session, or take over a step when the AI is about to do something wrong.
- Chat assistants beside the browser can discuss a page but cannot reliably act inside the page you are already using.
Duplex is a real desktop browser built for both of you. The AI works in the same tabs and the same logged-in session you see; every action is visible on the page; and when you touch the page, the AI yields instead of fighting you for input.
It is not a browser wrapper around a remote agent. It is the browser.
Highlights
- A real browser — tabs, address bar with search (Baidu / Bing / Google), back / forward / reload, loading state, themes, a wallpaper start page, customizable keyboard shortcuts, a full bookmark manager and session restore.
- Human-first collaboration — each AI task is bound to its tab. While you scroll, type or focus something, the AI keeps reading but pauses its own modifications on that page. A status bar lists human-controlled pages and hands each one back with a click.
- 25 browser tools —
snapshotturns a page into a compact DOM outline with[eN]refs; reads, clicks and typing run in-process (executeJavaScript/sendInputEvent), so the action itself no longer needs a DevTools attachment — locating the element still goes through Playwright over CDP. Iframe and open-shadow support, cancellable waits. - Panel-scoped agent control — Codex and Claude Code get an MCP server only for a panel-driven launch or resume; opencode gets a dedicated
duplexagent. Standalone agents do not get browser control and do not open Duplex on their own. - Built-in agent — connect any OpenAI-compatible provider (DeepSeek, Kimi, Qwen, GLM, Ollama, …), import providers from opencode, and let the browser drive itself with tools and skills.
- Visible actions — a cursor ring, element highlight and status bar show what the AI is doing; page annotations let you draw a box, circle, arrow or point and attach a question.
- Emergency stop — press
F2orCtrl+Shift+K(configurable) at any moment. Running tool calls are aborted, CLI children are terminated, pending confirmations are denied and queued messages are dropped. The pause survives a restart. - Local-first — settings, history, bookmarks, tabs and session data live on your machine. Prompts go only to the model provider or CLI you configured.
Feature tour
Built-in agent in action

The built-in model works through a real Word for the web session; every tool call appears as a card while the page stays visible.
External agents in the same panel

Codex and Claude Code sessions are mirrored in the same panel. Start or resume them from the tool selector; panel messages continue the same thread.
Visible AI actions

Every AI action is drawn on the page — cursor, element highlight and status bar. Press F2 to take over.
Page annotations

Draw a box, circle, arrow or point and attach a question; Duplex turns it into a structured brief for the AI.
Quick start
Installer (Windows / macOS / Linux)
- Download the latest installer from Releases:
Duplex Setup x.y.z.exe(Windows),.dmg(macOS, Apple Silicon / Intel) or.AppImage(Linux). - Run it and launch Duplex.
Build from source
npm install
npm run build # Electron app -> out/
npm run build:bridge # stdio MCP bridge -> dist-bridge/index.cjs
If Electron's binary download fails (e.g. behind a slow mirror), retry with:
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"; node node_modules/electron/install.js
Run it:
npm run dev # development mode with HMR
# or
npm start # preview the production build
Running a dev build next to the installed app? Set
DUPLEX_DATA_DIRto another directory so the two do not share settings or the local endpoint.
First run
- Open the AI panel with the AI button in the toolbar.
- Pick Built-in model and add an OpenAI-compatible provider, or pick an external CLI from the tool selector.
- Ask for something visible: "Open Hacker News and summarize the top three stories."
Connect your agents
The important rule since 0.2.10: standalone agent sessions do not get Duplex's browser tools. The tools are injected for a single panel-driven launch or resume. This keeps the default safe: an agent working in a terminal will not silently open a browser or take over your session.
Built-in model
Panel → Built-in model → Model settings. Add an OpenAI-compatible provider (base URL, API key, model name), or click Import from opencode to reuse an existing provider. Local models work through Ollama, e.g. http://localhost:11434/v1.
The built-in agent can load skills, read and write project files, and run commands; file and command actions use confirmation cards.
opencode
- Install the mirror plugin: copy
integrations/opencode/plugins/cobrowse-mirror.tsto~/.config/opencode/plugins/, or to.opencode/plugins/of a project. - Register the MCP server and a
duplexagent inopencode.json(project or global) — seeopencode.example.json. Normal sessions denyduplex_*; only theduplexagent allows them.
{
"permission": {
"*": "allow",
"duplex_*": "deny"
},
"agent": {
"duplex": {
"mode": "primary",
"permission": {
"*": "allow",
"duplex_*": "allow"
}
}
},
"mcp": {
"duplex": {
"type": "local",
"command": ["node", "C:\\path\\to\\Duplex\\dist-bridge\\index.cjs"],
"enabled": true
}
}
}
- In Duplex, select opencode in the tool selector and send the request there. The plugin delivers it to the active opencode session under the
duplexagent; only that panel-originated turn gets browser control. - To trigger it manually from opencode, select the
duplexagent explicitly.
Codex
Open the Duplex panel, select Codex in the tool selector, choose a model and start a session (or open an existing one from the history list).
- Duplex passes the MCP server to
codex exec/codex exec resumewith-carguments for that invocation only. There is no global[mcp_servers.duplex]entry. - Codex keeps its own authentication and model configuration from the Codex CLI.
- Codex transcripts are mirrored into the panel; a message typed there resumes the same thread with
codex exec resume.
Claude Code
Open the Duplex panel, select Claude Code, choose a model and start or resume a session.
- Duplex writes a temporary MCP config and passes it with
--mcp-config; it also appends the browser instruction and allows themcp__duplextools for that invocation. - There is no user-level
duplexMCP server in Claude Code's configuration. - Claude Code keeps its own authentication and model configuration; transcripts are mirrored and panel replies use
claude --resume.
Gemini, Qwen and custom CLIs
Gemini CLI, Qwen Code and user-defined CLI tools can be listed, started and mirrored in the same panel. They do not automatically receive Duplex's MCP server; their browser capability depends on the tools they ship with. If a CLI supports MCP, point it at dist-bridge/index.cjs explicitly.
Explicit MCP clients
Any MCP client can run the stdio bridge directly:
node C:\path\to\Duplex\dist-bridge\index.cjs
The bridge proxies tool calls to the running app and can launch it when it is not running. Each bridge process gets its own caller identity. This path is for users who want an explicit MCP integration; it is separate from the panel-scoped Codex / Claude / opencode flow.
MCP tools
| Tool | Description |
|---|---|
list_tabs / new_tab / close_tab / switch_tab / resume_tab |
Tab management — human and AI share the same tabs; resume_tab clears a stale lock or a human-handover pause |
navigate / search / history |
Open a URL (auto-searches if not a URL), search (Baidu default, or Bing / Google), back / forward / reload |
snapshot |
Page as text — compact DOM outline; interactive elements carry [eN] refs |
get_html / query |
Raw HTML, or detailed info for elements matching a CSS selector |
screenshot |
PNG screenshot of the visible page (for multimodal models) |
click / dblclick / hover |
Click / double-click / hover through Playwright; target accepts an eN ref or a CSS selector, and the action waits for the element to be actionable |
type / press |
Type text (optionally submitting) and press keys, including combos like Control+A |
drag |
Real drag and drop from one point or element to another |
select_option / upload |
Native <select> options, and file upload by absolute path |
scroll |
Scroll the page or a specific element into view |
wait |
Wait for time / selector / text — cancellable; yields with a reason while you are interacting |
get_console |
Read page console logs (errors and warnings) |
annotation_mode |
Enter/exit the annotation overlay (human draws a box/circle/arrow/point + question) |
evaluate |
Evaluate JS in the page; returns JSON-serializable results |
The built-in agent has six additional skill/file tools (read_skill, list_skill_files, read_skill_file, run_skill_script, write_file, run_command). They are marked internal: the bridge and the app's own MCP endpoint both skip them, so an external MCP client never sees them.
How it works

- The Electron main process serves a small local HTTP API on
127.0.0.1, protected by a per-launch bearer token. Endpoint information is written to~/.cobrowse/endpoint.json(or$DUPLEX_DATA_DIR/endpoint.json). dist-bridge/index.cjsis a stdio MCP server that proxies tool calls to that API and can launch the app when it is not running. It is the same bridge used by explicit MCP clients and by panel-driven agents.- Page automation is Playwright over the browser's own Chromium: the app reads
DevToolsActivePort, matchestargetIdto each tab and drives locators, iframes, open shadow DOM, cancellable waits and script evaluation — the same page you are looking at, not a separate automation instance. - A collaboration layer binds each task to its tab, serializes same-page writes, watches for real human input (wheel / touch / keyboard / focus) and pauses AI modifications per page; the status bar reflects the state and offers one-click resume.
- Panel-scoped injection: for Codex, Duplex adds the MCP server through
-c mcp_servers.duplex...; for Claude Code, it writes a temporary config and adds--mcp-config. Neither CLI is configured globally. - The opencode plugin pushes session events into the panel and long-polls for queued messages. Panel-originated prompts use the dedicated
duplexagent; normal sessions keepduplex_*denied. Deliveries are claimed once (60 s lease, renewed, ACK'd) and target the bound session. - Codex and Claude Code are mirrored from their local session transcripts (history + live tail); panel replies resume the same thread and stream back through the same tail. Launches are matched by structured session IDs, not "the most recently modified file".
- Browser state (tab order, HTTP(S) URLs, the active page) is saved on exit and restored on the next start. External scripts can push messages with
POST /api/chat { "text": "..." }.
Security and privacy
Duplex gives an AI access to your real browser session, including login state, cookies and local data. Treat that as a high-stakes capability.
- You are always in control. The AI yields while you interact with a page; the emergency stop cuts AI actions, CLI children and queued messages. In the built-in agent, tool calls that write files or run commands use confirmation cards.
- Local-first. Settings, browser data, history, bookmarks and sessions are stored locally. Prompts and page content go only to the model provider or CLI you configured; Duplex does not run a cloud relay.
- Explicit imports. Provider credentials imported from opencode or Codex are read-only copies; imported OAuth credentials are restricted to official hosts.
- Panel-scoped agents. Codex and Claude Code receive no global MCP entry; opencode denies
duplex_*outside theduplexagent. A terminal agent cannot silently open Duplex. - Data directory. Everything lives under
~/.cobrowseby default; setDUPLEX_DATA_DIRto isolate dev builds, tests or multiple profiles.
How Duplex compares
| Duplex | browser-use | Browser MCP | Playwright MCP | AI browsers (Atlas / Comet) | |
|---|---|---|---|---|---|
| Form | Desktop browser (Electron app) | Python automation framework | MCP server (browser extension) | MCP server (Microsoft) | Closed-source product |
| Who uses the browser | Human and AI share the same tab and the same live session | AI only (separate automation instance) | AI drives your current Chrome | AI only (Playwright instance) | AI assistant alongside/operating |
| What the AI sees | DOM outline snapshot + source + screenshots | Vision + DOM | Screenshots + a11y tree | Accessibility tree | Internal |
| Human collaboration | Real-time side-by-side; the emergency-stop key interrupts the AI anytime | Logs afterwards | Human spectates | Human spectates | Limited intervention |
| When both act on one page | The AI yields while you interact; per-page pause + one-click resume | — | — | — | — |
| Connectable AI | Built-in models + panel-driven opencode / Codex / Claude Code; mirrored Gemini / Qwen; explicit MCP clients | Bring your own LLM | Any MCP client | Any MCP client | Official model only |
| Conversation visibility | Live side-panel mirror: opencode text + tool calls; Codex / Claude Code transcript chat | Logs/terminal | In the client | In the client | In-app |
| Data | Local-first | Local/cloud | Local | Local | Cloud |
In one line: browser-use / Playwright MCP let the AI run a flow for you; Duplex lets the AI use the browser together with you — same tab, same session, and when you both reach for the page, you go first.
Known limitations
- Primary actions run through Playwright/CDP, but some fallbacks use synthesized DOM events (for example
el.click()when the actionability check fails). Sites that depend on fully trusted input,contenteditableor custom widgets may need manual coordination; side effects already applied cannot be undone. - Cancellation granularity: in-flight Playwright calls are bounded by 200–250 ms polling. A click, submit or write that already completed cannot be rolled back.
evaluatecleans up timers / RAF / fetch inside its scope, but cannot revoke callbacks registered elsewhere (e.g. viadocument.defaultView); advanced uses are being constrained further.- Element refs are snapshot-scoped: after navigation or large DOM changes, take a fresh
snapshot(stale refs fail with a clear message instead of clicking something wrong). - Codex / Claude Code sessions are mirrored from local transcripts; their formats are controlled by those CLIs. Ambiguous launch identities are refused rather than guessed.
- Gemini, Qwen and custom CLIs are mirrored and can be launched, but do not automatically receive Duplex's MCP tools.
- opencode message de-duplication relies on the plugin; if it stays disconnected longer than the lease, an accepted-but-unacknowledged message may be delivered twice. Exact dedupe needs upstream message IDs.
- Direct MCP clients each get a per-process caller identity; an explicit task start / end / handoff protocol is planned for 0.3.x.
- Built-in multimodal image context, site-specific custom widgets and cross-platform interaction have not been fully verified. Windows is the primary target; macOS/Linux builds are provided but less tested.
- The built-in agent is a convenience option: local or smaller models are noticeably less reliable at long tool-use chains than a full opencode setup.
Roadmap
- v0.3.x — collaboration, continued.
- An explicit task-lifecycle / handoff protocol for MCP callers (start, end, restore) and finer-grained cancellable action steps.
- Fallbacks for
contenteditableand custom widgets; a richer CLI session lifecycle; multimodal verification. - Community backlog: command palette, tab search, reader mode, bookmark HTML import / export, and more — tracked in
docs/待办与用户反馈.md.
Development
npm run dev # dev mode (electron-vite, HMR for the renderer)
npm run typecheck # TypeScript checks (node + web)
npm test # unit tests (vitest, 599 cases)
npm run smoke # end-to-end smoke test (launches the bridge and a real browser)
npm run dist # build the Windows installer (electron-builder)
Self-contained smokes (a hidden Electron plus a temporary data directory — they never touch your own sessions):
node tests/playwright-connection-smoke.mjs # the Playwright layer against a hidden fixture browser
node tests/private-029-smoke.mjs # main-process collaboration scenarios
Debug helpers:
GET /api/debug/ui-snapshot— captures the current window to~/.cobrowse/ui-snapshot.png.POST /api/debug/panel-eval— runs JS in the panel renderer (only when the app is started withCOBROWSE_DEBUG_UI=1).POST /api/debug/ui-action— drives panel actions (used by tests, e.g.{"action":"panel-mode:opencode"}).- Logs:
~/.cobrowse/app.log.
Duplex MCP questions
What tools does Duplex MCP provide?
It exposes 8 tools, including snapshot, screenshot, drag, scroll, wait.
How does Duplex differ from other AI browsing tools?
Unlike hidden automation instances or chat assistants that cannot act on your current page, Duplex is a real browser where the AI works in the same tabs and logged-in sessions you see.
Can I stop the AI if it starts doing something wrong?
Yes, you can use an emergency stop by pressing F2 or Ctrl+Shift+K to abort running tool calls and terminate CLI children.
Is my data stored remotely?
No, Duplex is local-first, meaning your settings, history, bookmarks, tabs, and session data stay on your machine.
How does the AI interact with the page?
The AI uses 25 browser tools including reading, clicking, and typing that run in-process, while using Playwright over CDP for element location.
