Connects MCP agents to your logged-in Chrome browser to observe tabs, fill forms, and execute automated workflows through a persistent JavaScript workspace.
Also known as jackwener/BrowserMCP, @jackwener/browsermcp
- Stars
- 171
- Tools
- 16
- Downloads, 30 days
- 4,218
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is BrowserMCP MCP?
BrowserMCP connects MCP agents to your logged-in Chrome browser to observe tabs, fill forms, and execute automated workflows through a persistent JavaScript workspace. It exposes 16 tools, such as session_finish, tabs_list, claim_tab.
Summary generated from the project's README
About BrowserMCP MCP server
BrowserMCP provides a way for MCP clients to interact with your existing Google Chrome session. By using a local host and a Chrome extension, it allows AI agents to observe open tabs, navigate websites, and fill out forms using your active logins. This setup is designed for developers using clients like Claude Desktop, Cursor, or Claude Code who need an agent to perform tasks on websites where they are already authenticated.
The system operates through a local connection using Node.js 22 or newer. It features a persistent JavaScript workspace where agents can execute code, maintain variables, and manage tab lifecycles. Users can also utilize built-in site adapters for platforms like Reddit, Bilibili, and Twitter/X to run verified workflows. The service manages browser organization by grouping agent-created tabs and cleaning them up after a session, while ensuring user-owned tabs remain untouched.
What you can do with it
- 1Automate authenticated web tasksAn agent can navigate through your existing browser session to search, read pages, and fill out forms on logged-in websites.
- 2Execute site-specific workflowsDevelopers can use pre-built commands for specific platforms like Reddit or Bilibili to perform structured actions.
- 3Create custom browser toolsYou can inspect website requests and define new, reusable MCP tools by creating site adapters.
- 4Manage complex browser sessionsAgents can use a persistent JavaScript environment to keep data and tab handles active across multiple calls.
Written from the project's README. Every use case is checked against a quote from it.
How to install BrowserMCP MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall BrowserMCP MCP in Claude Code
$ claude mcp add browsermcp -- npx -y @jackwener/browsermcpInstall BrowserMCP MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"browsermcp": {
"command": "npx",
"args": [
"-y",
"@jackwener/browsermcp"
]
}
}
}Install BrowserMCP MCP in VS Code
.vscode/mcp.json
{
"servers": {
"browsermcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@jackwener/browsermcp"
]
}
}
}Install BrowserMCP MCP in VS Code CLI
$ code --add-mcp '{"name":"browsermcp","type":"stdio","command":"npx","args":["-y","@jackwener/browsermcp"]}'Install BrowserMCP MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"browsermcp": {
"command": "npx",
"args": [
"-y",
"@jackwener/browsermcp"
]
}
}
}Install BrowserMCP MCP in Codex
$ codex mcp add browsermcp -- npx -y @jackwener/browsermcpInstall BrowserMCP MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.browsermcp] command = "npx" args = ["-y", "@jackwener/browsermcp"]
Install BrowserMCP MCP in Gemini CLI
$ gemini mcp add -s user browsermcp npx -- -y @jackwener/browsermcpInstall BrowserMCP MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"browsermcp": {
"command": "npx",
"args": [
"-y",
"@jackwener/browsermcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @jackwener/browsermcp 0.0.43 in an isolated container with no network and no keys. It answered and listed 16 tools.
BrowserMCP MCP tools 16
Read from the server with tools/listsession_finishActionFinish the task: unmarked agent tabs close, user tabs and deliverables release, handoff tabs retain ownership and usable handles. Returns closed/released/retained/failed separately.
tabs_listRead-onlyList session and unclaimed tabs without claiming, loading or focusing. Continue with cursor alone. Use tabId directly; claim an unclaimed backendId before operating.
claim_tabActionAcquire an existing user tab. Exactly one selector: backendId, active:true, or unique URL/title. Does not create a tab.
open_tabActionExplicitly create a new tab. Prefer navigate_tab to reuse an existing tab.
navigate_tabActionNavigate the specified session tab in place. Never creates a tab, including on failure. Reuse its tabId for subsequent operations. For SPA readiness, pass ready (the same conditions as tab.expect) and timeoutMs; DOM settling alone does not guarantee loaded content.
close_tabActionClose exactly one session-owned tab. For a user tab, claim it first. Closing is different from releasing control.
tabs_closeActionClose explicit session tab handles; returns an outcome for each tab, including partial failure. Never targets the current tab implicitly.
release_tabActionLeave the tab open and relinquish session control. Its handle becomes unusable until claimed again.
tab_observeRead-onlyObserve a session tab. Continue captured state using options.cursor. No implicit tab selection.
tab_actActionPerform one action on an explicit session tab. Input delivery does not prove task completion; observe or verify the resulting page before deciding the next action.
doctorRead-onlyRuntime status: browser connection, extension features and protocol warning (if versions differ), site/command counts, sessions. A protocol mismatch blocks browser commands until the host and extension are updated.
sites_searchRead-onlyFind reusable site commands before implementing the same task with browser actions or scripts. No query: list available sites with sample commands. With a task, site, or domain as query: find matching commands. Results include args[{name,type,required,help,default,choices}] for site_run. Do not invent parameters.
| session_finish | Finish the task: unmarked agent tabs close, user tabs and deliverables release, handoff tabs retain ownership and usable handles. Returns closed/released/retained/failed separately. | Action |
| tabs_list | List session and unclaimed tabs without claiming, loading or focusing. Continue with cursor alone. Use tabId directly; claim an unclaimed backendId before operating. | Read-only |
| claim_tab | Acquire an existing user tab. Exactly one selector: backendId, active:true, or unique URL/title. Does not create a tab. | Action |
| open_tab | Explicitly create a new tab. Prefer navigate_tab to reuse an existing tab. | Action |
| navigate_tab | Navigate the specified session tab in place. Never creates a tab, including on failure. Reuse its tabId for subsequent operations. For SPA readiness, pass ready (the same conditions as tab.expect) and timeoutMs; DOM settling alone does not guarantee loaded content. | Action |
| close_tab | Close exactly one session-owned tab. For a user tab, claim it first. Closing is different from releasing control. | Action |
| tabs_close | Close explicit session tab handles; returns an outcome for each tab, including partial failure. Never targets the current tab implicitly. | Action |
| release_tab | Leave the tab open and relinquish session control. Its handle becomes unusable until claimed again. | Action |
| tab_observe | Observe a session tab. Continue captured state using options.cursor. No implicit tab selection. | Read-only |
| tab_act | Perform one action on an explicit session tab. Input delivery does not prove task completion; observe or verify the resulting page before deciding the next action. | Action |
| doctor | Runtime status: browser connection, extension features and protocol warning (if versions differ), site/command counts, sessions. A protocol mismatch blocks browser commands until the host and extension are updated. | Read-only |
| sites_search | Find reusable site commands before implementing the same task with browser actions or scripts. No query: list available sites with sample commands. With a task, site, or domain as query: find matching commands. Results include args[{name,type,required,help,default,choices}] for site_run. Do not invent parameters. | Read-only |
Show all 16 toolsShow fewer tools
site_runExecute an existing adapter using this session’s browser context. No enable or setup step is required. args must match the args list from sites_search. Invalid args return invalid_args with details.expected. Valid commands execute directly, including writes.
docs_getRead-onlyNo name: compact REPL quickstart and available topics. Pass name for a topic; use member with api-reference for one class or method, e.g. Tab.act or Tab.network.
jsPrimary browser workspace. Persistent Node REPL: variables, functions, classes and top-level await; use let for reusable bindings. Pre-bound browser, sites, tools, recon. Discover and claim an existing tab first; use helper.navigate_tab({tabId, url}) to reuse it. Only open_tab or browser.tabs.new explicitly creates a tab. helper exposes the same typed commands as MCP, including close_tab. observe returns a compact action map, not HTML; follow nextCursor with tab.observe({cursor}) for remaining captured pages, or scope with {target:{selector:"#main"}}. tab.read() returns an object: use result.text and tab.read(result.next) to continue. For focused content use tab.read({target:{role:"main"}}) or an article locator. Wait for SPA content with tab.expect({target:{selector:"article"},visible:true},{timeoutMs:15000}); use a unique target when multiple articles exist. tab.evaluate defaults to 10000 ms; pass timeoutMs for longer work. Reuse tab across calls; await tab.act({action:"click", target:{ref:"..."}}) with an observed ref, then observe. Batch determined steps and return at new decision points. Await API calls; dispatched API work is drained before returning. Ordinary errors preserve bindings. Last expression is returned; do not use top-level return. nodeRepl.write(value) adds output. Page JS uses tab.evaluate. docs_get with no arguments returns quickstart/topics; api-reference with member:"Tab.act" gives exact types.
js_resetStop JavaScript, clear bindings and close explicit subscriptions; browser tabs stay open. pendingCalls reports already dispatched API operations that may still complete. Wait until doctor shows javascript.pendingCalls:0 before more js; inspect the page before retrying actions.
| site_run | Execute an existing adapter using this session’s browser context. No enable or setup step is required. args must match the args list from sites_search. Invalid args return invalid_args with details.expected. Valid commands execute directly, including writes. | |
| docs_get | No name: compact REPL quickstart and available topics. Pass name for a topic; use member with api-reference for one class or method, e.g. Tab.act or Tab.network. | Read-only |
| js | Primary browser workspace. Persistent Node REPL: variables, functions, classes and top-level await; use let for reusable bindings. Pre-bound browser, sites, tools, recon. Discover and claim an existing tab first; use helper.navigate_tab({tabId, url}) to reuse it. Only open_tab or browser.tabs.new explicitly creates a tab. helper exposes the same typed commands as MCP, including close_tab. observe returns a compact action map, not HTML; follow nextCursor with tab.observe({cursor}) for remaining captured pages, or scope with {target:{selector:"#main"}}. tab.read() returns an object: use result.text and tab.read(result.next) to continue. For focused content use tab.read({target:{role:"main"}}) or an article locator. Wait for SPA content with tab.expect({target:{selector:"article"},visible:true},{timeoutMs:15000}); use a unique target when multiple articles exist. tab.evaluate defaults to 10000 ms; pass timeoutMs for longer work. Reuse tab across calls; await tab.act({action:"click", target:{ref:"..."}}) with an observed ref, then observe. Batch determined steps and return at new decision points. Await API calls; dispatched API work is drained before returning. Ordinary errors preserve bindings. Last expression is returned; do not use top-level return. nodeRepl.write(value) adds output. Page JS uses tab.evaluate. docs_get with no arguments returns quickstart/topics; api-reference with member:"Tab.act" gives exact types. | |
| js_reset | Stop JavaScript, clear bindings and close explicit subscriptions; browser tabs stay open. pendingCalls reports already dispatched API operations that may still complete. Wait until doctor shows javascript.pendingCalls:0 before more js; inspect the page before retrying actions. |
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubBrowserMCP
A browser service for MCP agents, connected to the Chrome you're already logged into.
BrowserMCP 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 · 中文指南
What you can do
- 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). Agents use a persistent JavaScript REPL for browser work and structured site tools for verified workflows.
The npm package is @jackwener/browsermcp; the command is browsermcp.
Quick start
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.
1. Install the Chrome extension
Install BrowserMCP Connector from the Chrome Web Store →
For an extension version ahead of the Web Store, download the manual-install zip from GitHub Releases and follow the manual installation steps.
2. Install the npm package and set up the connection
npm install -g @jackwener/browsermcp
browsermcp setup
Keep 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 browsermcp setup --clients opencode. It adds a global MCP entry while preserving your other settings.
For DeepSeek Harness (dsh), run browsermcp setup --clients none, then add the same npm package to your dsh profile:
dsh plugin --profile web add @jackwener/browsermcp
Restart 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 browsermcp setup --clients pi. See the Pi setup steps.
3. Start using it
Restart or reconnect your MCP client, then ask:
Use BrowserMCP to read the top five Hacker News stories and summarize them with links.
You can rerun browsermcp setup to repair the browser registration or select newly installed clients to configure. Selected clients have their browsermcp entry updated to a stable launcher; other server entries are preserved. The launcher follows Homebrew upgrades within the same formula. If Node or the package moves, rerun setup. For a read-only startup and connection check, run browsermcp doctor.
Connection issues? See troubleshooting.
Local configuration
Data, configuration, and user adapters live in ~/.browsermcp. The launcher is ~/.browsermcp/bin/browsermcp-launcher (.cmd on Windows). Run browsermcp setup to register it with Chrome and your selected MCP clients.
This is a fresh configuration: old directories, environment variables, and adapter import aliases are not used. Remove obsolete MCP client entries manually. User adapters import @jackwener/browsermcp/adapter-sdk.
Usage
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 |
|---|---|
| Browser workspace | js, js_reset |
| Discover and run site commands | sites_search, site_run |
| Learn the API | docs_get (quickstart, topics, or an exact API member) |
| Diagnose connection and execution | doctor |
| Finish a browser session | session_finish |
The browser workflow is observe → act → verify → finalize, expressed in js using the same object model as adapters:
let tab = await browser.tabs.new('https://example.com/');
await tab.observe();
Variables, functions, classes and Tab handles persist across calls. After inspecting the result, use await tab.act(...) and await tab.expect(...) or observe again. Keep working data in variables and return only relevant evidence. docs_get {} provides a compact quickstart; {name:"api-reference",member:"Tab.act"} provides exact types. No repository documentation access is required.
Use browser.user.openTabs({query,limit}) and browser.user.claimTab(...) for user tabs. The lookup returns a discovery envelope: read items, matched, totalInScope, excluded and hasMore. It returns up to 20 recent matches by default; continue with offset: nextOffset. tab.release() leaves a tab open; tab.close() closes it. session_finish closes agent tabs not kept and releases borrowed tabs. js_reset stops JavaScript and clears bindings while leaving tabs open; already dispatched operations may still complete. All API methods are awaited.
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.
How it works
MCP client → browsermcp 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.
The MCP launcher can start before Chrome. It keeps the client connection open and reconnects when the Chrome-owned host appears or restarts. Browser operations and site adapters use that host; run browsermcp doctor if it stays unavailable.
Connections are local-only: standard MCP stdio to the launcher, then Unix domain socket (macOS/Linux) or named pipe (Windows) to the host. No port or token configuration. See browser selection and configuration.
Browser access and permissions
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.
Documentation
| Guide | Contents |
|---|---|
| Installation and configuration | Source installs, browser profiles, local connections, 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 |
Development
git clone https://github.com/jackwener/browsermcp.git browsermcp
cd browsermcp
npm install
npm run typecheck
npm 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 # core regression tests
npm run smoke:setup # isolated setup and Native Messaging end-to-end check
npm run smoke:feedback # real Chromium + extension: what an agent observes, does and verifies
npm run smoke:observation # real Chromium + extension: frames, shadow DOM, refs, reads, pagination
npm run smoke:native # real Chromium + extension through MCP, the REPL and the native bridge
The three real-browser checks need Chromium (BROWSERMCP_TEST_CHROMIUM to point at it) and run without a display with BROWSERMCP_TEST_HEADLESS=1.
Keep the automated suite focused on MCP browser flow, REPL persistence and interruption, connection recovery, session isolation, tab cleanup, and adapter execution. Prefer these integration checks over per-adapter mapping tests and implementation-detail assertions. Run 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, run the three real-browser checks. docs/api-reference.md is generated during the build; update its TypeScript source rather than editing the generated file.
Maintainers: use the release workflow to publish the npm package and GitHub Release.
Found a bug or have a feature request? Open an issue. See CHANGELOG.md for release history.
License and credits
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.
Native browser APIs
The REPL also exposes browser.chrome.call(method, argsArray) for native Chrome APIs, tab.cdp.send(method, params) for an explicit Tab, and writable Main World tab.evaluate(script, {arg, timeoutMs}). Use browser.chrome.describe("tabs.query") for on-demand signatures and runtime availability. Chrome/CDP events and page/extension logs support bounded subscriptions with explicit loss/reset information. Read docs_get {name:"capabilities/chrome"} inside MCP for examples and lifecycle rules, or the native capabilities guide.
For development, npm run smoke:native runs the new flows in a disposable Chromium profile after a build. Set BROWSERMCP_SMOKE_CHROME to a Chromium executable when it is not available in the local Playwright cache. It does not modify the everyday browser profile or native-host registration.
Common browser tools
Use tabs_list → claim_tab to reuse an existing page, then navigate_tab, tab_observe and tab_act. Only open_tab creates a new page. close_tab/tabs_close close explicit session tabs; release_tab leaves a tab open. session_finish reports closed, released, retained and failed tabs separately. Handoff tabs remain usable in the same session.
The persistent js workspace exposes the same commands through helper, including helper.navigate_tab({tabId,url}) and helper.close_tab({tabId}). Chrome APIs, CDP and Adapter authoring remain available through the existing object API.
Built-in Adapter metadata is generated into adapters/manifest.json. Startup and search read this catalog; command modules load when executed. After changing built-in adapters, run npm run gen:adapters and commit the generated manifest (the build regenerates it too). Writable user adapters continue to be indexed from their modules.
BrowserMCP MCP questions
How do I add BrowserMCP MCP to Claude Code?
Run claude mcp add browsermcp -- npx -y @jackwener/browsermcp in your terminal. Add --scope user to make it available in every project.
How do I add BrowserMCP MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does BrowserMCP MCP provide?
It exposes 16 tools, including session_finish, tabs_list, claim_tab, open_tab, navigate_tab.
What can BrowserMCP do with my browser?
It allows MCP clients to search, read pages, fill forms, and navigate through your existing, logged-in browser sessions.
Which browsers are supported?
While designed for Google Chrome, the local host also supports other Chromium-based browsers like Edge and Brave.
Does it work with Claude Desktop or Cursor?
Yes, it works with various MCP clients including Claude Desktop, Cursor, Claude Code, and others.
How is the connection secured?
Connections are local-only, using standard MCP stdio to the launcher and then a Unix domain socket or named pipe to the host.