Browser Profile MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Browser Profile MCPList my open tabs in the work Chrome profile."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Browser Profile MCP
Let Codex or Claude Code control the tabs in your already-open Chrome profiles, using their existing website logins. Your AI login stays in the coding agent.
Set up each profile once. After that, open your coding agent and use the browser tools: the agent starts the local bridge automatically. There is no daily npm start step and no terminal to leave running.
Requires a local Codex or Claude Code client and Chrome 118+ on the same computer. You do not need an OpenAI or Claude login inside the Chrome profile.
Download
Get the latest release:
Extension ZIP: unzip it into a permanent folder, open
chrome://extensionsin the intended profile, enable Developer mode, and choose Load unpacked with that folder. Pin the extension and open its side panel.Bridge ZIP: the local Node.js helper used by your coding agent. The extension's setup prompt tells your agent where to download it, verify its checksum, and install it. You do not need to start a separate app or leave a terminal running.
The bridge needs Node.js 20+ and npm. Its source is also bundled inside the extension as a fallback. The public source repository is guilhermegm/browser-profile-mcp. Release ZIPs include source and dependency manifests; they do not bundle Node.js or your profile credentials.
Related MCP server: cc-chrome
Connect through your coding agent
Name this profile in the extension, for example
workorpersonal.Copy the setup prompt and paste it into Claude Code, Codex, or another local coding agent. The agent handles installation and configuration.
Paste the code your agent gives you and click Connect.
Start a new agent session. Open a new session in your coding agent, then send the message shown in the panel, such as
Use browser-work MCP to list my open tabs.Use Copy message to copy it. The panel switches to Connected when your agent connects.
Setup previews render the extension's actual panel with the monkey logo and sample states for a profile named work. They contain no live account data or pairing codes. Click an image to enlarge it.
The profile is registered once in the coding agent's user-level MCP configuration and works across its projects. There are no project-scope or provider-configuration dropdowns in the extension.
The prompt includes the profile name, extension ID, and installation identity. The agent reuses an existing helper or downloads the matching bridge from GitHub Releases and verifies it against SHA256SUMS. It checks Node.js 20+, installs production dependencies, and registers its client. The helper source bundled in extension/local-helper/ is a fallback. The agent returns a pairing code; users do not need to locate a repository or assemble commands. Setup does not launch another Chrome or run browser tests.
Redo setup under Connection settings clears this extension's saved pairing and returns to step 1, keeping the profile name. It does not reset server credentials or remove agent configuration. Reconnect resumes the saved connection, including after it was disconnected. Clipboard access and stopping actions are also under Connection settings.
1. Prepare this project and create a pairing
Keep this project in a permanent folder: agent registration uses absolute paths to its launcher. In a terminal opened in that folder, install dependencies once:
npm install --ignore-scriptsCreate a pairing for the Chrome profile you want to control:
npm run profile -- workUse a different name for each Chrome profile, such as work, personal, or client-acme. Names use lowercase letters, numbers, and hyphens, up to 40 characters. The name is your label for this pairing; choose the actual Chrome profile when installing and pairing the extension.
The command prints a pairing code and exact registration commands for each agent and scope. Creating a pairing saves credentials; your coding agent starts the connection after registration. Keep the pairing code private.
Running the same command again preserves credentials and the saved port. To choose a port explicitly:
npm run profile -- work --port 94442. Install and pair in the intended Chrome profile
Open the Chrome profile you want to control, then visit
chrome://extensions.Enable Developer mode.
Click Load unpacked and select this project's
extensionfolder.Pin Browser Profile MCP from Chrome's extensions menu, then click it to open the side panel.
Paste only the pairing code and click Connect.
After saving the code, step 4 tells you to start a new agent session and shows the message to send. It switches to Connected when your agent connects. The ON badge means the browser is connected. Listing tabs confirms access through the intended coding agent.
Keep a regular window open in this profile. Pairing survives Chrome and computer restarts. Closing the side panel keeps the background connection available. The first extension installation to connect with a pairing claims it; another Chrome profile needs its own pairing.
3. Choose your agent and where it is available
The normal extension flow asks the coding agent to register this profile in its user-level MCP configuration. It handles provider-specific configuration and preserves unrelated entries.
The examples below are for manual setup and development. If you intentionally use project-scoped configuration, run registration from the target project. When changing scope, remove only the matching old entry so it cannot override the replacement.
Claude Code
This project only: run the printed command from the project where you use Claude Code. This scope is private to you and is available only in that project:
claude mcp add --transport stdio --scope local browser-work -- /absolute/path/to/node /absolute/path/to/browser_mcp/mcp.js work --port 9333All my projects: choose this scope explicitly to make the server available across your projects on this computer:
claude mcp add --transport stdio --scope user browser-work -- /absolute/path/to/node /absolute/path/to/browser_mcp/mcp.js work --port 9333These are examples; copy the generated command to use your real paths, profile name, and port. Choose one scope for the intended setup. If a server already exists, update or replace the entry in that scope; for example, claude mcp remove browser-work --scope local before adding a replacement there. The --chrome flag belongs to Claude Code's separate built-in integration and is not needed here.
Codex
All my projects: run the printed codex mcp add browser-work -- ... command. It registers the server in your user configuration, shared by local Codex clients.
This project only: paste the displayed block into the intended project's .codex/config.toml. Codex loads this file only for trusted projects. The block has this form:
[mcp_servers.browser-work]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/browser_mcp/mcp.js", "work", "--port", "9333"]
startup_timeout_sec = 20
tool_timeout_sec = 60Use the generated paths and port. Update an existing browser-work block instead of appending a duplicate. User-wide configuration is in ~/.codex/config.toml; local CLI, IDE, and desktop clients share it.
See official OpenAI MCP documentation and Claude Code's registration scopes. For a session that should access only one browser profile, configure or enable only that profile's server. A session given both browser-work and browser-personal can access both.
4. Verify one simple task
Start a new agent session after registration. Check that the intended server is configured:
Codex:
codex mcp list, from the intended project if you chose project-only configuration.Claude Code:
claude mcp get browser-work, from the intended project.Inside either agent's CLI:
/mcpshows server status. Resolve any approval, disabled-server, or connection issue shown there.
A registered server alone does not prove browser access. Send this read-only task to the coding agent, replacing browser-work if you chose another name:
Use browser-work MCP to list my open tabs. Report the profile name and tab titles only. Do not open, navigate, or change any tabs.
Success: the agent returns this profile's tab titles, and the side panel shows Connected. Check that the titles belong to the Chrome profile you intended. Each newly attached session confirms its own access by listing tabs; confirmations reset if the browser connection is lost.
If the browser is connected but no agent is attached, register or start the intended agent. If the server is absent from the agent's list, check the selected scope and project. If it is present but failed, inspect its status and the panel's connection message. These checkpoints separate registration, browser connection, and page-operation failures.
5. Use your browser
Open your normal Chrome profile and start the configured agent. It starts the shared connection automatically. There is no daily npm start step. Use the same profile registration in multiple sessions, and register it separately with the other provider when needed. For example:
Use browser-work to find my dashboard, read the page, and tell me what needs my attention.
Actions operate on your real website sessions. The coding agent supplies its usual tool approval prompts. Chrome shows a debugging indicator while a tab is attached; the extension detaches automatically after five idle seconds. Tasks and chat stay in the coding agent; the side panel handles pairing and connection controls.
Tool reference
Tool | What it does |
| List tabs; create a tab in an existing window; focus or close a tab. |
| Navigate an existing tab to an HTTP(S) URL. |
| Read compact visible text from the main content, a CSS selector, or an element ref. |
| Get element refs from a bounded accessibility subtree. Scope by CSS selector/ref; |
| Find elements by exact accessible name and/or role, optionally within a selector/ref, and add their refs. |
| Click, hover, type, press keys, scroll, select an option, or answer a page dialog. Include |
| Run 1–8 known actions on one tab, then return a compact read. Other commands on that tab wait until the batch and cleanup finish. |
| Capture the visible viewport as a JPEG. |
Tools use explicit tabId values. Clicks accept refs or screenshot coordinates. Typing appends by default; clear: true replaces a field's contents. Mod+a uses Command on macOS and Control elsewhere. A snapshot replaces your session's refs for that tab; find adds refs. Another session taking a snapshot does not invalidate your refs; page navigation or debugger recovery does. Embedded frames and canvas interfaces may require screenshots and coordinate actions. File upload/download management and recording are outside this version's toolset.
Visible agent cursor
Agent clicks, hovers, and scrolls show an orange arrow in the controlled tab. Its first movement starts at the center of the viewport. Later movements start at the last cursor position, including after the overlay fades or the debugger detaches for idle time. The cursor travels for about 260–500 ms depending on distance; the action waits for that travel before clicking or scrolling. Clicks display a ring after arrival. The cursor fades out after about 2.6 seconds without mouse activity. Reduced-motion settings disable the glide and expanding ring; hidden tabs skip the travel delay. Keyboard-only actions do not move the cursor.
The overlay ignores mouse input, stays out of accessibility snapshots and text reads, and is removed when disconnecting or navigating. It also expires automatically if Chrome detaches the debugger. A short, bounded travel delay makes actions visible without another model/tool round trip. Ref actions recheck the live target after travel, and clicks check again after hover feedback and immediately before pressing. A moving, removed, disabled, or covered target fails rather than clicking stale coordinates. Screenshot coordinates remain explicit positions; they do not identify a particular element.
Version 0.5.3 updates the extension, store artwork, website graphics, and setup previews with the supplied proboscis monkey icon. It includes guided agent registration, saved ports, pairing-conflict recovery, and connection verification. Follow Apply this update below to reload the extension and reconnect your agents.
Debugger banner while idle
After a tab has no queued or running commands for five seconds, the extension detaches that tab's debugger. Chrome can dismiss the debugging banner once no controlled tabs remain attached; activity in another tab may keep the shared banner visible. The saved pairing, local connection, and green connected badge remain active. The next page command reattaches automatically. Tab listing does not need the debugger.
An entire batch stays attached until it finishes. An open JavaScript alert/confirm/prompt also keeps the debugger attached until the dialog is answered. Clicking Chrome's Cancel button still stops control and requires Connect in the extension to resume.
Idle detachment keeps each session's element refs. On reattach, the controller compares the main frame, navigation loader, and document identity before reusing them. Navigation during the idle gap invalidates the refs, and the agent must take a fresh snapshot.
Faster reads and actions
Prefer read when you need content rather than controls. It extracts visible text directly, choosing a visible main/[role=main], then article, then the page body. A plain read or screenshot enables Page events for dialogs but skips DOM and Accessibility initialization. Optional selector or ref targets a smaller area; choose one. maxChars defaults to 12,000, with a 50,000 maximum. This limits returned text, not the cost of reading a large element. Results include truncated and totalChars, so a clipped read is explicit. read preserves your existing element refs.
For example, call read with an actual tab ID returned by tabs:
{"tabId": 123, "selector": "[role=main]", "maxChars": 12000}Use find when you know a control's exact accessible name or role:
{"tabId": 123, "name": "Search", "role": "button", "maxResults": 5}Add selector or ref to restrict the search to a subtree. Find appends refs and reports totalMatches and truncated. Prefer an exact name and a narrow scope: Chrome computes matching accessibility information for the selected subtree, and maxResults limits output only. A broad role-only query can still be expensive.
Use snapshot when you need to discover controls. Its default compact view removes layout containers and repeated labels. Scope it to the area you need:
{"tabId": 123, "selector": "[role=main]", "maxNodes": 100, "maxDepth": 12}Snapshots acquire the selected subtree incrementally, with up to 48 accessibility requests, a retained-node budget of min(4000, maxNodes * 4 + 100), and a depth limit (default 24, maximum 64). maxNodes limits rendered output (default 300, maximum 1,000). Results report acquisition counts and truncated when any limit clips content. A single Chrome response can contain more nodes than the controller retains; these budgets do not guarantee a fixed amount of browser CPU work. Use a narrower scope or find if content is clipped. compact: false includes more detail within the same budgets.
An act call can return the resulting content without another model round trip. Replace the example ref with one from your current snapshot:
{
"tabId": 123,
"action": "click",
"ref": "REF_FROM_YOUR_SNAPSHOT",
"read": {"mode": "text", "selector": "[role=main]"}
}Choose read: {"mode": "snapshot"} instead when you need the next page's controls. Follow-up reads wait until the DOM has been quiet for 120 ms, up to settleMs (default 800, maximum 3,000). settleMs: 0 skips that wait. The returned settled field describes this bounded DOM wait (null when skipped); it does not guarantee that a slow network request has finished. A navigation or read failure never replays the action. If the action succeeded but reading failed, the result reports done: true and an error; read the page again.
Use batch for steps whose targets are already known, such as typing into a search field and pressing Enter:
{
"tabId": 123,
"actions": [
{"action": "type", "ref": "SEARCH_FIELD_REF", "text": "example", "clear": true},
{"action": "key", "key": "Enter"}
],
"read": {"mode": "snapshot"}
}Batches contain at most eight actions on the same tab, start no more steps after their 20-second budget, and stop at the first failure. Each step can optionally include its own read; a final text read is included by default. Results report completed, failedStep when applicable, and individual outcomes. Completed actions are not rolled back or retried. Inspect partial failures before continuing. If a step's snapshot produces new refs, let the model inspect them before choosing another target; do not guess refs inside the same batch.
Clipboard shortcuts
Agent-generated copy, cut, and paste shortcuts are disabled by default, including for existing pairings. To allow them, open this profile's side panel and check Allow system clipboard shortcuts. The setting persists for that pairing and resets when it is forgotten or replaced. A batch requiring a blocked shortcut is rejected before any of its actions start; the permission is also checked before each shortcut.
The system clipboard is shared with other Chrome profiles and applications. Opting in allows agents to paste that content into a webpage and to overwrite clipboard contents. Enabled clipboard commands/batches are queued across profiles in the shared bridge. This coordinates extension commands; other applications and manual clipboard use remain independent. The switch governs tool-generated keyboard shortcuts, not clipboard features that a website is already permitted to use by Chrome. Typing text with type does not use the clipboard.
If a clipboard command is cancelled, times out, or loses its connection, later clipboard commands are held until the extension confirms cleanup. If that confirmation cannot arrive, use Stop current actions in the affected profile's side panel; clipboard work resumes only after that profile reconnects with a confirmed clean debugger state. Other page work can continue.
Multiple sessions and providers
Use the same registered browser-work pairing in as many Codex or Claude Code sessions as you need. The profile has no exclusive controller lease. Commands on the same tab run in order, and a whole batch holds that tab through its actions, reads, and cleanup. Up to four independent tabs can proceed concurrently. Tab listing bypasses page queues. Creating, focusing, or closing tabs, and commands/batches using clipboard shortcuts, form profile-wide barriers: they wait for earlier page commands and finish before later page commands start. Other profiles have independent queues.
When adding another coding-agent provider, register the same helper path, profile, and saved port in that client's configuration. The existing bridge should be shared. Do not choose another port or redo the extension pairing merely because an agent is already connected. The v0.5.3 launcher can reuse the identical protocol-3 runtimes from the v0.5.1 and v0.5.2 artwork releases; unknown versions or different protocols still require an update.
Each session keeps its own snapshot refs. The tabs and website state are still shared: if another session navigates the same tab, take a fresh snapshot. Use separate tabs for unrelated tasks or different Chrome profiles for separate website accounts. Closing one agent cancels its queued work and stops its remaining actions without disconnecting the other sessions. Cancellation cannot undo an action already sent to Chrome.
The queue accepts up to 32 commands. A command that waits more than 20 seconds returns an explicit error without starting. Started commands have an overall 45-second deadline including queue time. Cancelled or expired queued commands do not execute later.
Protocol calls, debugger attachment, and Chrome APIs also have worker-side deadlines (normally 10 seconds per call). DOM settling has its own settleMs + 250 ms worker deadline, so a paused page timer cannot hang the queue. Cancellation or a stalled protocol call releases held input and detaches the affected tab before another action can start there. Cleanup has a 1.5-second bound; if detachment cannot be confirmed, that tab remains in recovery and global barriers wait. Other tabs and tab listing remain available. A timed-out tab/window mutation retains its conflicting lane until Chrome's original operation settles. Recovery invalidates refs, and commands are never replayed automatically. This cannot undo an action Chrome already received.
Apply this update
Reload Browser Profile MCP at
chrome://extensionsin each paired profile. Pairing is preserved.Stop the previous bridge as described below, then restart/reconnect your
browser-<profile>MCP server in Codex and Claude Code so both clients load version 0.5.3. The next connection starts the updated bridge automatically. Existing stdio configuration and saved pairing do not need to be regenerated.
If an old bridge is still running, close its MCP connections in all agents and allow roughly a minute for automatic shutdown before reconnecting. A manually started bridge can be stopped with Ctrl+C.
Already using the previous HTTP setup?
Your extension pairing can stay as it is. Switch the agent's configuration once:
Stop the old
npm startprocess with Ctrl+C if it is running.Run
npm run profile -- workagain to print the new launcher configuration. Existing credentials are preserved.In Claude Code, run
claude mcp remove browser-workin the project/scope where you added it, then run the newly printed stdio add command.In Codex, replace the old
browser-workblock containingurlandhttp_headerswith the newly printedcommand/argsblock. Do not append a duplicate table.Start a new agent session. If the extension was already loaded, click its Reload button at
chrome://extensions, then click the toolbar icon to open the new side panel. Its saved pairing persists.
After this switch, the agent manages startup automatically.
Connection lifecycle
Closing the side panel leaves control connected. A 20-second WebSocket heartbeat and Chrome API activity run in the background while connected, independently of the panel and debugger. Startup/install events and an alarm reconnect an enabled extension after worker restarts; transient duplicate-connection errors retry automatically.
Disconnect stops this profile's connection, detaches its debuggers, and stays disconnected until you click Connect.
Stop current actions cancels the profile's current and queued commands, detaches debuggers, and reconnects. Sessions can share the profile without using this button.
Forget pairing removes this extension installation's local credentials.
Five idle seconds detaches debuggers automatically while keeping the connection and pairing ready for the next command.
Closing an agent cancels its session's queued and remaining work. Other agents and profiles keep using the shared bridge.
An automatically started bridge exits after roughly a minute with no connected agent sessions. An agent killed without cleanup is detected through its missing heartbeat first. Enabled extensions wait and reconnect when the next agent starts the bridge.
Multiple MCP sessions and providers can use each profile. Commands are serialized per tab and batches stay together, with profile-wide barriers for shared browser operations. Independent tabs and profiles can be controlled concurrently. Manual browsing shares the same tabs.
Troubleshooting
Situation | What to do |
Waiting for a coding agent | Use Connect another agent to copy the setup prompt, paste it into your coding agent, and start a new agent session if needed. |
Browser connected, but no agent attached | Browser connection alone is not agent registration. Keep the browser connected and use Connect another agent to set up the intended client. |
Agent attached, but tab access unconfirmed | Use Copy message to ask your agent to list tabs. Verify each new agent session separately. |
Server missing in another project | Check registration scope. Claude local scope and Codex project configuration apply only to the intended project. Choose all-project scope explicitly if desired. |
Could not start the local bridge | Read |
Port belongs to another app or older bridge | Stop the previous |
Node executable cannot be found | Regenerate the setup output after installing/updating Node. Use the printed absolute executable path. |
Profile disconnected | Click Reconnect. If it is already waiting/retrying, start or reconnect the configured agent and read the panel's status; Disconnect under Connection settings stops retries. The bridge never substitutes another profile. |
Disconnects when the side panel closes | Reload the current extension. If it happens again, reopen the panel and expand Last connection interruption to see the recorded reason and time. |
Secure bridge authentication failed | Reload the extension and stop/reconnect the previous bridge and agent launchers. The extension will not trust a server merely because it occupies the configured port. |
System clipboard shortcuts are disabled | Opt in with Allow system clipboard shortcuts in this profile's side panel, or use |
Another agent controls this profile | An older bridge is still running. Stop its MCP connections, let it shut down, then reconnect to load this update. |
Browser command queue is busy/full | This command did not start. Let the running batch finish, then try again. |
Pairing assigned to another Chrome profile | Copy the setup prompt again so your agent creates an unused pairing for this installation. Reloading alone cannot change the binding. |
Cannot attach / another debugger | Close DevTools or detach the other browser automation extension for that tab. |
Control stopped in Chrome | You dismissed Chrome's debugging indicator. Click Reconnect to resume. |
Unknown or expired ref | Ask the agent to take another snapshot. |
A page dialog is open | Use |
Internal Chrome page / Web Store | Use a regular HTTP(S) website tab. Incognito is excluded. |
Command timed out | Inspect the page before retrying. The action might have completed. Commands are never automatically replayed. |
Tab still recovering | Wait for cleanup to finish; other tabs and tab listing remain available unless a shared tab/window mutation is still pending. Reload the extension if recovery cannot finish. |
Target moved or is covered | Inspect the page and get fresh refs, or take a screenshot. The stale ref click was not sent. |
Bridge disconnected while the agent was running | Reconnect the MCP server in your agent; its launcher starts the bridge again. |
To deliberately move a pairing or replace its credentials, reset its tokens and installation binding. This revokes the old pairing and interrupts its agent sessions:
npm run profile -- work --resetForget the old extension pairing, paste the new code, and restart/reconnect the agent's MCP server. The launcher reads the current credentials from disk, so its configuration does not need new tokens.
To choose a different port during setup:
npm run profile -- work --port 9444The port is saved with the profile and retained when you print setup again or reset it. The older BROWSER_MCP_PORT=9444 environment-variable form is also supported. An explicit flag takes precedence over the environment, then the saved port. Changing the port requires updating both the extension pairing and the agent's launcher configuration.
Automated checks
To refresh the setup previews, install the development dependencies and Playwright's Chromium, then run npm run capture:setup. This renders the actual panel HTML, CSS, and UI logic with sample setup states. It does not connect to a bridge, open existing Chrome profiles, or use the system clipboard.
Run the unit and bridge integration tests:
npm testnpm test is noninteractive. It covers setup commands and scope selection, custom-port persistence, command quoting, authentication, encrypted-message tampering/replay rejection, queue ordering/cancellation, real stdio launcher connections, per-session verification, pairing conflicts/reset, and automatic bridge startup/shutdown.
Browser checks are disabled by default, including when using npm run test:all. Running npm run test:browser without opting in reports a skipped test and does not launch a browser. Fresh browser instances caused browser/OS permission prompts during this session, so those runs were stopped at the user's request.
The optional browser suite uses Playwright's downloaded Chromium and disposable profiles. It is enabled only with BROWSER_MCP_BROWSER_TESTS=1 in addition to npm run test:browser; it can require browser/OS permission interaction. It was not completed as a reliable, permission-free final run. Do not count it as a release readiness pass.
All fixtures use temporary directories, disposable credentials, and ephemeral ports. They do not open existing Chrome profiles, read saved pairings, or contact AI providers. Actual Codex/Claude account sessions and platform-specific browser behavior remain separate release checks.
Implementation
mcp.js: stdio MCP launcher; starts/reuses the shared bridge, connects over an authenticated encrypted WebSocket, forwards its tools, maintains a heartbeat, and closes its session on exit.bridge.js: profile credentials, encrypted agent/extension connections, concurrent tab queues shared across providers, a shared clipboard queue, and cancellation.npm startremains available for optional foreground debugging. Legacy plaintext HTTP MCP endpoints are disabled.secure-transport.js: adapts the authenticated encrypted channel to the MCP SDK transport interface.extension/secure-channel.js: shared mutual authentication, directional encryption, sequence checking, and bounded handshake/message processing.settings.js: local profile files and shared connection settings.extension/onboarding.js: the agent setup prompt, shared safe command formatting, launcher metadata, scope choices, and the first tab-listing task. Pairing codes carry launcher paths so setup does not depend on a running bridge; older pairings receive them over the authenticated connection.extension/background.js: connection lifecycle, automatic idle debugger detachment, tab ownership/document checks, Chrome DevTools Protocol commands, session-scoped snapshots, input, cursor feedback, follow-up reads, and batches.extension/scheduler.js: shared per-tab queues, bounded concurrency, metadata bypass, and global barriers.extension/debugger.jsandextension/deadline.js: lazy protocol domains, worker deadlines, attachment generations, and cancellation/recovery.extension/accessibility.jsandextension/target.js: scoped accessibility acquisition/formatting and live pointer target checks.extension/protocol.js: shared bridge/extension version and command-lane rules.extension/content.js: compact visible text extraction and bounded DOM settling, run in the inspected page through CDP.extension/cursor.js: isolated cursor overlay, movement/click animations, and automatic cleanup.extension/sidepanel.*: pairing, agent setup guidance, and connection controls in Chrome's side panel.extension/manifest.json: permissions and service worker registration.
The bridge binds only to 127.0.0.1. Both agent and extension connections prove possession of their separate profile secrets before application messages are accepted. Fresh client/server nonces, purpose/profile/identity/protocol binding, and role-separated HMAC proofs authenticate each connection. HKDF derives separate AES-256-GCM keys for each direction; encrypted messages have strict sequence checks. Reusable tokens are never sent over either connection. The public health endpoint checks availability/version only and cannot establish trust. A counterfeit listener or relay cannot read tool payloads or forge authenticated commands; it can still prevent a connection from working. Old bearer HTTP commands and plaintext WebSocket messages are rejected.
Extension connections additionally require a Chrome extension origin and the paired installation identity; agent sockets reject browser origins. Page inspection, target checks, and select helpers run in an isolated JavaScript world so page scripts cannot replace the APIs used by those helpers. The page can still change its real DOM and present misleading content: isolation does not make webpage content trustworthy instructions.
Credentials and background logs are stored in .browser-mcp/, excluded by .gitignore, with private file permissions. Keep pairing codes private. Agent configuration only names the local launcher and profile. Browser-profile routing does not sandbox an agent's filesystem access: a process that can read these credential files or modify the installed extension/launcher already has authority over those pairings.
The launcher and extension run on the same computer as the coding agent. The controller never starts Chrome or creates a browser window. Browser tool isolation is separate from the coding agent's terminal and filesystem permissions.
Status: version 0.5.3 refreshes the artwork and setup previews with the supplied proboscis monkey icon. Noninteractive checks cover setup, encrypted transport, packaging, and bridge/launcher integration. Browser checks are opt-in; full Chrome/provider end-to-end validation remains incomplete. The README setup previews use sample UI states, not live account connections. See Automated checks above for scope and limits.
Packaging the extension
Run npm run build:helper before preparing an extension release. It copies only the helper source, production dependency manifests, and setup notes into extension/local-helper/; it excludes development tools, installed dependencies, and credentials. It refuses to build over a bundle containing runtime state. Copy a helper out of the extension before using it as a runtime installation.
Run npm run build:release with Node.js and Python 3 to create the extension ZIP, bridge ZIP, and SHA256SUMS in dist/. The packager uses explicit file allowlists and rejects unexpected files, credentials directories, installed dependencies, and symlinks. A locally generated brand-kit ZIP is included when present. Release downloads are published on GitHub Releases.
Upload only the contents of extension/ to CWS, with manifest.json at the ZIP root. The helper source is included for the setup agent; it runs locally under Node, not inside Chrome. Never include a .browser-mcp/ credentials folder or an installed node_modules/ directory.
Branding and publication assets
Brand artwork, extension icons, Chrome Web Store promotions, website assets, and reusable prompts are in branding/. The current logo uses the supplied full-color proboscis monkey artwork with its transparent background. The untouched source is branding/logo/monkey-source.png; PNG exports preserve the artwork and transparency, and SVG layouts embed the raster image. The 128 px store icon includes transparent outer padding. Open branding/index.html for the visual guide and branding/prompts.txt for the prompt pack. Chrome Web Store submission files include listing copy, privacy declarations, reviewer instructions, and three 1280 × 800 captures of the actual installed panel with a disposable pairing. npm run build:cws packages the handoff; nothing is submitted automatically. The older marked capture layouts remain drafts.
License, privacy, and security
MIT licensed; see LICENSE and NOTICE for bundled font and dependency notices. See PRIVACY.md for the data flow and SECURITY.md to report a vulnerability privately. Do not include pairing codes or local .browser-mcp/ files in public issues or pull requests.
This server cannot be deployed
Maintenance
Related MCP Connectors
Browser MCP for logged-in tasks. Uses your Chrome — credentials stay local. Zero-token replay.
Logs your AI agent into websites, catches verification codes, and asks you before anything risky.
Connect AI agents to your own Chrome with scoped access, approvals, and verified task results.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables CLI coding agents to interact with your live browser tabs via MCP, using your real sessions and cookies without a sandbox.MIT
- AlicenseBqualityCmaintenanceEnables browser control through your existing signed-in Chrome profile, letting MCP clients like Claude Code manage tabs, navigate, inspect pages, and perform real user interactions via tool calls. Works with any model backend without needing Playwright or a fresh browser profile.21MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to control an existing signed-in Chrome profile through MCP stdio, using its current tabs, cookies, and logins without pairing or a separate browser. It exposes tab management, page interaction, screenshots, and Chrome DevTools Protocol commands.32 npmMIT
- AlicenseNot gradedqualityAmaintenanceLets AI coding tools directly control the user's already-open, logged-in Chrome to read pages, navigate, click, type, screenshot, inspect network/storage, and automate browser tasks through local MCP tools.1 npmISC