A browser service for MCP agents, connected to the Chrome you're already logged into.
opencli-mcp lets MCP clients observe and operate your Chrome tabs through a local extension and host. Optional site adapters package verified workflows as reusable tools.
Quick start · Usage · Documentation · 中文指南
- Work with logged-in websites. Search, read pages, fill forms, and navigate through your existing browser session.
- Use optional site commands. Discover built-in adapters for Twitter/X, Bilibili, and Reddit when a site-specific command helps.
- Add site adapters. Inspect a site's requests, verify an API, and define an explicit reusable MCP tool.
- Keep browser work organized. Agent-created tabs live in named groups and are cleaned up after use. Tabs borrowed from the user are never closed by session cleanup.
Works with MCP clients including Claude Code, Codex, OpenCode, Cursor, Claude Desktop, DeepSeek Harness (dsh), and Pi (with pi-mcp-adapter). Clients can use structured tools for individual actions or a persistent JavaScript session for multi-step workflows.
You need Node.js 22 or newer, Google Chrome, and an MCP client. The local host also supports Chromium-based browsers such as Edge and Brave; see installation details.
Install opencli-mcp from the Chrome Web Store →
npm install -g opencli-mcp
opencli-mcp setupKeep Chrome open. setup connects the extension to the local program, asks which MCP clients to configure, registers only your selection, and checks the browser connection. If you have not installed the extension yet, it opens the Chrome Web Store for you.
For Cursor, Claude Desktop, and other MCP clients, choose manual and copy the configuration printed by setup into your client's MCP settings. It uses absolute paths so desktop apps can find the program.
For OpenCode, run opencli-mcp setup --clients opencode. It adds a global MCP entry while preserving your other settings.
For DeepSeek Harness (dsh), run opencli-mcp setup --clients none, then add the same npm package to your dsh profile:
dsh plugin --profile web add opencli-mcpRestart dsh web. The package's dsh bundle uses dsh's MCP client to connect to the browser service. See the dsh setup details.
For Pi, install pi-mcp-adapter, then run opencli-mcp setup --clients pi. See the Pi setup steps.
Restart or reconnect your MCP client, then ask:
Use opencli-mcp to read the top five Hacker News stories and summarize them with links.
You can rerun opencli-mcp setup to repair the browser registration or select newly installed clients to configure. Existing MCP client settings are preserved. For a read-only connection check, run opencli-mcp doctor.
Connection issues? See troubleshooting.
Tell your agent what you want to do; it discovers and calls the MCP tools. For example:
- “Open Hacker News, read the newest stories, and keep the most useful page open for me.”
- “Search for site commands that work with Bilibili.”
- “Explore this website's search, then create a reusable tool for the same query workflow.”
For integrations and custom workflows, the main tools are:
| Task | Tools |
|---|---|
| Browse a page | tab_open, tab_observe, tab_read, tab_act, tab_expect |
| Find or use an existing tab | tab_list, tab_claim |
| Keep a tab open or close it | tab_release, tab_close |
| Finish a browser session | session_finalize |
| Discover and run site commands | sites_search, site_run |
| Define a site adapter | tools_define |
| Run multi-step JavaScript | js, js_reset |
| Read built-in documentation | docs_list, docs_get |
The browser workflow is observe → act → verify → finalize. tab_observe is the action map (accessibility snapshot with element references). tab_read is the document text; pass its nextStart back as start to continue a long, unchanged page. Actions wait for their targets to be ready before dispatching browser input.
Browser control starts explicitly with tab_open or tab_claim; tab_list shows session tabs and, with user:true, up to 20 recent tabs available to claim. Use query to find an older tab by title or URL. tab_release leaves a tab open and gives up control. tab_close closes it, including a claimed user tab. Session cleanup closes agent-created tabs that you do not keep and releases claimed user tabs; any cleanup failures are reported for retry.
Inside the js tool, you can also call site commands directly:
await sites.enable('reddit');
const posts = await sites.reddit.hot({ subreddit: 'programming', limit: 5 });
posts;See the JavaScript guide, API reference, and tool authoring guide for complete examples.
MCP client → opencli-mcp launcher → local host ⇄ Chrome extension → website
stdio Native Messaging your session
Chrome starts the local host through Native Messaging. The extension operates browser tabs using Chrome's debugger APIs and Playwright's injected locator engine. The host exposes browser operations, site commands, and tool authoring through MCP. Each MCP client connection has its own tab and JavaScript session, so one client's cleanup does not close another client's tabs.
Chrome and the extension must be connected before the MCP launcher starts. Both browser operations and site adapters use that same connection. Run opencli-mcp doctor if the client cannot connect.
The host also supports Streamable HTTP for remote clients. See remote access and configuration.
The extension requests browser permissions including debugger, cookies, and access to all URLs so it can operate logged-in sites. Connected agents can act with the access available in your browser session.
Site commands execute directly without additional approval prompts. The read/write classification describes their effects. See configuration.
| Guide | Contents |
|---|---|
| Installation and configuration | Source installs, browser profiles, remote clients, settings, troubleshooting |
| 中文指南 | Chinese project overview and detailed usage |
| Site commands | Discovering, enabling, and running adapters |
| JavaScript guide | Persistent sessions and the object API |
| API reference | Generated reference for browser and tool APIs |
| Creating tools | Define and verify reusable site adapters |
| Tab lifecycle | Claiming tabs, grouping, and cleanup |
| Errors | Error codes and recovery |
git clone https://github.com/jackwener/opencli-mcp.git
cd opencli-mcp
npm install
npm run typechecknpm install builds the project through its prepare script. To connect a development build to Chrome, follow the unpacked-extension instructions.
npm run build:ext # rebuild the extension
npm test # unit tests
npm run smoke:setup # isolated setup and Native Messaging end-to-end check
npm run smoke:browser # end-to-end check with a connected Chrome extensionRun the tests relevant to your change. npm run check runs typecheck, build, and the full test suite when a broader check is needed. For browser changes, use the browser smoke test. docs/api-reference.md is generated during the build; update its TypeScript source rather than editing the generated file.
Found a bug or have a feature request? Open an issue. See CHANGELOG.md for release history.
Apache-2.0. Some browser helpers and adapters were adapted from OpenCLI; no OpenCLI dependency or compatibility layer is required. Uses Playwright's injected locator engine. Endpoint analysis is inspired by jsluice.