Skip to main content
Want Skyvern MCP to automate sites in the Chrome browser you already use? The Skyvern Agent Chrome extension lets a local MCP server drive your real Chrome profile, including its logged-in sessions and cookies. Unlike skyvern browser serve, which starts a separate Chrome browser with a copied profile, the extension controls explicitly shared tabs in your actual browser. Chrome 136 and later ignores --remote-debugging-port for the default profile, so an extension is the only way to automate that browser directly.

​
Requirements

  • Chrome 125 or later
  • A local Skyvern MCP server connected over stdio
Hosted MCP is not supported yet.

​
Install the extension

The recommended setup command prints the unpacked extension directory, opens Chrome’s extensions page when possible, and prints the remaining steps:
Then enable Developer mode, click Load unpacked, and select the printed directory. If your MCP server is already running with the extension bridge, the command also opens the one-click pairing page. Otherwise, start the MCP server and run skyvern browser extension-pair. For manual setup:
  1. Print the directory containing the extension:
  2. Open chrome://extensions in Chrome.
  3. Enable Developer mode.
  4. Click Load unpacked.
  5. Select the directory printed by the command.

​
Pair the extension

With your MCP server running, ask your MCP client to create a browser session. If the extension is not paired, Skyvern opens a secure pairing tab automatically. You can also start the flow explicitly:
Click Approve in the pairing page, then approve the pairing again in the Skyvern Agent confirmation tab that opens. The pairing link expires after two minutes and can be used only once; retry the browser-session request or rerun the command if it expires. As a manual fallback, copy the pairing token to your clipboard:
Then open the Skyvern Agent popup, paste the token, and click Connect. Treat the pairing token like a password. The one-click URL contains only a short-lived nonce in its fragment; Skyvern does not put the pairing token in a URL or expose it through MCP tools.

​
Configure MCP

Set BROWSER_TYPE=extension-connect in the environment for your local MCP server. For example, use this stdio configuration in an MCP client that accepts JSON:
Alternatively, start the local MCP server with the browser extension bridge enabled:
The environment setting starts the bridge lazily when skyvern_browser_session_create needs it. The flag starts the bridge in the background as the MCP server boots, so the server answers your client’s initialize request without waiting for the bridge. Either way, skyvern_browser_session_create starts the bridge if it is not up yet. Check the local setup without exposing the pairing token:
The command reports the extension directory, whether token configuration and file permissions are present, and whether the configured loopback port is accepting connections. The default port is 19777; a custom port is configured with SKYVERN_BROWSER_EXTENSION_PORT for the MCP server and under Advanced settings in the popup.

​
Use your browser

After the extension is connected, a typical MCP flow is:
  1. Call skyvern_browser_session_create to connect Skyvern to the extension.
  2. Call skyvern_navigate to open a page.
  3. Call skyvern_observe to inspect the page and identify actions.
  4. Call skyvern_execute or skyvern_click to interact with the page.
Selectors remain the primary way to target elements. skyvern_click and skyvern_type also accept x and y coordinates in viewport CSS pixels, measured from the top-left of the web content. Provide both coordinates together and do not combine them with a selector. Coordinates must be finite and non-negative. skyvern_execute can pass the same coordinates to click and type actions. Coordinates align with skyvern_screenshot(full_page=False) and are not scaled by the device pixel ratio.
Membership in the Chrome tab group named Skyvern Controlled is the consent boundary. Dragging a tab into that group shares it with Skyvern; dragging it out immediately revokes access. The Add to Skyvern Controlled and Remove from Skyvern Controlled buttons in the Skyvern Agent popup make the same group-membership changes. The extension never discloses tabs outside the group to Skyvern. Skyvern’s scope includes:
  • Existing tabs you explicitly add to Skyvern Controlled, by dragging or with the popup
  • Tabs Skyvern creates and adds to Skyvern Controlled
  • Popups opened by a controlled tab and added to Skyvern Controlled
When Skyvern attaches to a controlled tab, Chrome displays its debugger infobar; Skyvern never hides it. Clicking Cancel in that infobar immediately revokes access to the tab, and Skyvern does not automatically reattach. Skyvern also never closes or restarts your Chrome browser. The extension connects outbound to a bridge bound only to 127.0.0.1. The default endpoint is ws://127.0.0.1:19777/extension/v1. Pairing-token authentication verifies both the extension and the local MCP bridge, and the token is never included in the URL. The extension refuses to control chrome://, chrome-untrusted://, chrome-extension://, devtools://, edge://, file://, Chrome Web Store pages on chromewebstore.google.com, and about: pages other than about:blank.

​
Limitations

  • Downloads and file-chooser management are not supported yet.
  • Incognito windows are not supported.
  • Opening DevTools for a controlled tab detaches Skyvern and revokes access to that tab.
  • Only one local Skyvern MCP process can control the extension at a time.
  • Hosted Skyvern MCP cannot use the extension yet.
  • Chrome internal pages, extension pages, DevTools, local files, the Chrome Web Store, and the other restricted targets listed above cannot be controlled.

​
Troubleshooting

Follow the steps in order:
  • Run skyvern browser extension-install and follow its numbered setup instructions.
  • Start the MCP server with --browser-extension or BROWSER_TYPE=extension-connect.
  • Run skyvern browser extension-status and confirm it reports the bridge listening on the configured port.
  • Run skyvern browser extension-pair, approve the browser page, then approve the Skyvern Agent confirmation tab.
  • If one-click pairing fails, open the Skyvern Agent popup and use skyvern browser extension-token as the manual paste fallback.
  • Add at least one controllable tab to Skyvern Controlled, then retry.
The server loads a large Python dependency tree before it serves its first request. That usually takes a few seconds, but the first start after an install or upgrade — and any start on a busy machine — can take considerably longer than an MCP client’s default startup window.Watch for this: when a local server fails to mount, coding agents fall back to the identically named hosted Skyvern tools, so a run that looks like it is driving your Chrome is really driving a cloud browser. Confirm the server is connected before you trust an extension flow.Raise your client’s startup timeout:
  • Claude Code: set MCP_TIMEOUT (milliseconds) in the environment that launches it, for example MCP_TIMEOUT=180000.
  • Codex: raise startup_timeout_sec for the server entry in ~/.codex/config.toml.
To see where the time goes, read the client-launched server’s mcp_boot_ready log line after it connects. The event is emitted only after the server successfully handles initialize; it reports spawn_to_serve_ms alongside the env_ms and tool_import_ms phases that make it up.
The bridge uses port 19777 by default. Set SKYVERN_BROWSER_EXTENSION_PORT in the MCP server environment, configure the same port under Advanced settings in the popup, then restart the MCP server and reconnect the extension.
Stop the MCP server, delete ~/.skyvern/browser_extension_token, and restart the server. Run skyvern browser extension-pair and approve both browser steps. Use skyvern browser extension-token and paste the new token into the Skyvern Agent popup only as a manual fallback.If SKYVERN_BROWSER_EXTENSION_TOKEN is set in the MCP environment, remove it before rotating the token file because the environment value takes precedence.
Close DevTools if it is open, then add the tab to Skyvern Controlled again by dragging it into the group or using the popup. If you clicked Cancel in Chrome’s debugger infobar, adding the tab again restores consent; Skyvern never reattaches automatically.