Skip to main content

Browser Agents

Browser Agents Local

Let Claude Code, Codex, Cursor, or any local MCP client use the Chrome you already have open: every profile, your logins, and your tabs. Part of the free, open-source pre.dev MCP server.

Browser Agents Local is the local edition of Browser Agents: it lets the coding agent on your computer drive the Google Chrome you already have open. Your agent can open a tab in your work profile, read a dashboard you are signed in to, fill in a form, click through a flow, and screenshot the result. There is no second browser to set up and no site to sign in to again.

It is part of the free, open-source pre.dev MCP server, @predotdev/mcp, which shows up as predev in your agent. The same server also carries pre.dev’s cloud tools: cloud Browser Agents, specifications, and project plans. One command sets up both.

It works with any coding agent: Claude Code, Codex, Hermes, Pi, OpenClaw, Cursor, GitHub Copilot, Cline, Gemini CLI and Antigravity, OpenCode, Zed, Goose, and more than 20 others, plus any agent that can run a shell command. Run as many agents as you like at the same time. They share one connection to Chrome, so Chrome asks you to allow it once each time Chrome starts.

Coming from Claude in Chrome? Switch in two steps. Your Chrome profiles, tabs, and logins carry over.

Cloud or Local

CloudLocal
Browserpre.dev’s browsersYour own Chrome, every profile
How it runsYou send a task and a URL by REST, the SDKs, or the browser_agent MCP tool, and get structured data backYour coding agent drives Chrome step by step with the chrome_* tools
SitesPublic pages; no persistent login profilesAccounts you are already signed in to: dashboards, internal tools, anything behind a login
ScaleMany tasks in parallelOne Chrome on your computer, shared by all your agents
SetupNoneOne command, setup, for every agent on your Mac, or /chrome in the pre.dev CLI
CreditsPer taskOnly for plain-words actions; everything else is free

Use Cloud to run browser work from your application or at volume. Use Local when your coding agent needs the Chrome you already use. With the pre.dev MCP server, your agent has both and picks per task.

Quick start

You need macOS, Google Chrome, and Node.js 22 or later (check with node --version). Run one command:

npx -y @predotdev/mcp setup

It walks you through everything:

Sign in to pre.dev

Your browser opens pre.dev with a short code. Sign in, or create a free account, and approve. Setup saves your workspace API key for every agent, so there is nothing to copy. Already signed in to the pre.dev CLI? Setup uses that login.

Add it to every coding agent on your Mac

Setup installs a stable copy and registers it as predev, with full paths that also work in desktop apps, in each agent it finds: Claude Code, Codex, Hermes, Pi, OpenClaw, Cursor, Windsurf, GitHub Copilot CLI, Antigravity, Gemini CLI, Cline, Kiro, Qwen Code, Factory Droid, Augment, Amp, Kilo Code, Zed, Kimi Code, Junie, Warp, Rovo Dev, OpenHands, LM Studio, OpenCode, VS Code, VS Code Insiders, Claude Desktop, and the pre.dev CLI, which gets only the Chrome tools because it has the cloud tools built in. Codex gets a 900-second tool timeout, so specs and cloud runs can finish. Setup replaces any existing pre.dev entry, such as the hosted server at https://api.pre.dev/mcp under any name or an older Browser Agents Local install, because this server carries all of their tools. If an unrelated server already uses the name predev, setup leaves it alone and registers this one as pre-dev. It backs up each JSON config once, as <file>.bak-predev.

Connect to Chrome

The first time, setup asks you to turn on remote debugging at chrome://inspect/#remote-debugging and copies the address for you. Then Chrome asks Allow remote debugging?: click Allow. Setup lists your Chrome profiles once it is connected.

Restart your agent and try a prompt

List my Chrome profiles and the tabs I have open.

Then give it real work, such as reading a dashboard you are signed in to, filling in a form, or checking a flow in your app and screenshotting the result.

Or let your agent do it. Paste this into Claude Code or any coding agent:

Run `npx -y @predotdev/mcp setup` with a 10 minute timeout and tell me what to click.

Setup is safe to run again. The copy it installs keeps itself up to date, and running setup again also updates it. Chrome asks Allow remote debugging? once each time Chrome starts; updates keep the approved connection.

Use it in the CLI

In the pre.dev CLI, type:

/chrome

No CLI yet? Install it with:

curl -fsSL https://pre.dev/install | bash

From your next message, the agent can open tabs, read pages, click, and type in your own Chrome with the same tools, named mcp__predev__chrome_* there. It uses your CLI login, so there is nothing else to sign in to, and it adds only the Chrome tools because the CLI has pre.dev’s cloud tools built in. It needs Node.js 22 or later. The first time, Chrome asks Allow remote debugging? as above. Screenshots are saved as files on your computer, and the agent gets their paths. /chrome off turns it off.

If you ran setup after installing the CLI, there is nothing to do: setup adds the server to the CLI too.

Manual setup

setup does this for you. To add the server by hand, for example to an agent setup does not know, turn on remote debugging at chrome://inspect/#remote-debugging once, then give your agent a server named predev with the command npx -y @predotdev/mcp.

The key is optional: without one, the Chrome tools work, and plain-words actions and the cloud tools say how to sign in. To turn them on, sign in once with npx -y @predotdev/mcp login and leave the key out of the config, or put your workspace API key in the agent’s PREDEV_API_KEY.

Copy your pre.dev API key from Integrations → Built-in in the dashboard: pre.dev/projects/integrations for your personal workspace, or the Integrations page of a team workspace. Workspace keys start with pdk_.

The examples below set the key. If you signed in with login, leave it out: drop the env or environment entry, or the -e and --env flags.

claude mcp add --scope user predev -e PREDEV_API_KEY=your_key -- npx -y @predotdev/mcp
codex mcp add predev --env PREDEV_API_KEY=your_key -- npx -y @predotdev/mcp

Or add this to ~/.codex/config.toml. The longer timeout gives specs and cloud runs time to finish:

[mcp_servers.predev]
command = "npx"
args = ["-y", "@predotdev/mcp"]
env = { PREDEV_API_KEY = "your_key" }
tool_timeout_sec = 900

Add this to ~/.cursor/mcp.json, then restart Cursor:

{
  "mcpServers": {
    "predev": {
      "command": "npx",
      "args": ["-y", "@predotdev/mcp"],
      "env": { "PREDEV_API_KEY": "your_key" }
    }
  }
}

Add this to ~/.codeium/windsurf/mcp_config.json, then restart Windsurf:

{
  "mcpServers": {
    "predev": {
      "command": "npx",
      "args": ["-y", "@predotdev/mcp"],
      "env": { "PREDEV_API_KEY": "your_key" }
    }
  }
}

For Copilot agent mode, add this to .vscode/mcp.json in your project, or run MCP: Open User Configuration to add it for every project:

{
  "servers": {
    "predev": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@predotdev/mcp"],
      "env": { "PREDEV_API_KEY": "your_key" }
    }
  }
}

Add this to ~/.gemini/settings.json:

{
  "mcpServers": {
    "predev": {
      "command": "npx",
      "args": ["-y", "@predotdev/mcp"],
      "env": { "PREDEV_API_KEY": "your_key" }
    }
  }
}

Add this to opencode.json in your project, or to ~/.config/opencode/opencode.json for every project:

{
  "mcp": {
    "predev": {
      "type": "local",
      "command": ["npx", "-y", "@predotdev/mcp"],
      "environment": { "PREDEV_API_KEY": "your_key" },
      "enabled": true
    }
  }
}

Desktop apps do not load your shell’s PATH, so they need full paths. setup registers them for you. By hand, install once, then print the two paths you need:

npm install -g @predotdev/mcp
which node
echo "$(npm root -g)/@predotdev/mcp/src/bridge.mjs"

Add the predev entry under mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json. Set command to the which node output and the one argument to the second path, then restart Claude Desktop:

{
  "mcpServers": {
    "predev": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/opt/homebrew/lib/node_modules/@predotdev/mcp/src/bridge.mjs"],
      "env": { "PREDEV_API_KEY": "your_key" }
    }
  }
}

The same setup works for any app that cannot find npx or node.

hermes mcp add predev --command npx --args -y @predotdev/mcp
hermes config set mcp_servers.predev.timeout 900

Answer Y to turn on its tools. In a running chat, /reload-mcp picks it up.

pi mcp add predev -- npx -y @predotdev/mcp
pi mcp list

pi mcp list should show predev: connected. pi mcp add needs Pi 0.99 or newer. On an older Pi, run pi install npm:pi-mcp-adapter and add the predev entry to ~/.pi/agent/mcp.json by hand.

Add a local (stdio) server named predev with command npx and arguments -y @predotdev/mcp. Add the environment variable PREDEV_API_KEY unless you signed in with login. If the client cannot find npx, run setup, or use the full-path setup from the Claude Desktop tab. The setup guide has the command or file for GitHub Copilot CLI, Cline, Kiro, Qwen Code, Factory Droid, Augment, Amp, OpenClaw, Zed, Goose, Continue, Crush and more.

Every tool also runs from a shell, so any agent that can run commands (Aider, scripts, CI) can drive your Chrome:

npx -y @predotdev/mcp tools
npx -y @predotdev/mcp call chrome_open '{"profile":"Personal","url":"https://example.com"}'

Text goes to stdout, a screenshot is saved to a file and its path is printed, and the exit code is 1 when the tool failed.

Restart your agent. The first time it uses Chrome, Chrome shows Allow remote debugging?. Click Allow.

Check your setup

npx -y @predotdev/mcp check

The check confirms remote debugging is on, connects to Chrome, lists your profiles, and checks your key: the one saved by login, or PREDEV_API_KEY when it is set. It ends by naming anything left to fix.

Commands

Run each as npx -y @predotdev/mcp <command>.

CommandWhat it does
setupSign in, add the server to every coding agent on your Mac, and connect to Chrome. Run it again to update to the newest version
checkCheck your setup, list your Chrome profiles, and check your key
loginSign in to pre.dev again. Agents use the new key on their next call, with no restart
logoutForget the saved key
stopStop the background process. It starts again on the next tool call
uninstallRemove the server from every agent setup added it to, stop it, and delete its files and saved key
toolsList every tool and its arguments
call <tool> '<json>'Run one tool from a shell, for agents without MCP. See the No MCP tab in Manual setup

Tools

The Chrome tools run on your computer:

ToolWhat it does
chrome_profilesList your Chrome profiles (name and Google account) and how many tabs each has open
chrome_tabsList open tabs grouped by profile
chrome_openOpen a URL in any profile, in the background by default so you are not interrupted
chrome_navigateLoad a URL in a tab, or go back, forward, or reload
chrome_snapshotList the page’s interactive elements as short refs ([e1], [e2], …), including shadow DOM and same-origin iframes
chrome_clickClick by ref, CSS selector, visible text, or coordinates, with real mouse events
chrome_typeType into inputs, text areas, rich editors, and dropdowns
chrome_pressPress keys and shortcuts such as Enter, Tab, and cmd+a
chrome_scrollScroll the page or bring an element into view
chrome_readRead a page’s text, a part at a time for long pages
chrome_screenshotScreenshot the visible area or the full page
chrome_waitWait for text, a CSS selector, or a URL change; when you are signed in, wait for a plain-words condition
chrome_evalRun JavaScript in the page and return the result
chrome_uploadAttach local files to an upload button or file input
chrome_showBring a tab to the front so you can watch or take over
chrome_closeClose a tab
chrome_actClick or type into an element described in plain words, in one call; needs you to be signed in

The same server also lists pre.dev’s cloud tools, passed through on your key: browser_agent, browser_agent_get, browser_agent_list, fast_spec, deep_spec, get_spec, list_specs, and get_plan. They work as on the hosted server, with the same credits and plan access; see the MCP tool reference. Until you sign in, or on a plan without them, each one says how to turn it on.

A snapshot labels every tab with the profile it belongs to, so the agent always knows which account it is acting as:

Tab A137CF · Work <you@company.com> · Create your account
https://example.com/signup
[e1] textbox "Full name"
[e2] textbox "Email" value="you@company.com"
[e3] select "Plan" selected="Free"
[e4] checkbox "I agree to the terms" [unchecked]
[e5] button "Create account"

Plain-words actions

Two tools use your pre.dev account to understand the page, through the key saved by setup or login, or PREDEV_API_KEY:

  • chrome_act clicks or types into an element described in plain words, such as “the Create button in the dialog”, in one call and in under a second, with no snapshot. If it is not sure which element you mean, it lists the likely refs instead of acting. Use explicit refs from chrome_snapshot for irreversible steps such as send, pay, or delete.
  • chrome_wait with condition waits until a plain-words statement about the page is true, such as “the export has finished”.

Credits

Among the Chrome tools, plain-words actions are the only ones that call pre.dev. Each one costs a small fraction of a credit. Free workspaces get 10 credits of plain-words actions, enough for hundreds of them, separate from the AI Gateway trial. When they run out, your agent tells you and offers to open the billing page in your Chrome so you can subscribe; every other tool keeps working. They share the rate limits of your other API calls. Every other Chrome tool runs on your computer, never calls pre.dev, and is free.

Credits are the one currency for coding, planning, verification, browser tasks, and AI calls from your apps. One credit is worth $0.10.

GET /v1/usage lists plain-words actions under the model browser-agents-local, with path /browser/locate for chrome_act and /browser/check for conditions. Their errors follow the AI Gateway error format; see troubleshooting for what to do.

Configuration

setup and login save your workspace API key in ~/.predev/mcp/credentials.json, a file only you can read, and every agent uses it. Without a saved key, the server uses your pre.dev CLI login. It is the same key you use for the API, the AI Gateway, and cloud Browser Agents. The server reads the file on every call, so signing in again needs no restart.

To change that for one agent, set these in the env of its MCP entry:

VariableWhat it does
PREDEV_API_KEYA workspace API key (pdk_…). Overrides the saved key
PREDEV_API_URLThe pre.dev API to call. Default https://api.pre.dev
PREDEV_MCP_CLOUDoff lists only the Chrome tools, without pre.dev’s cloud tools
CHROME_MCP_USER_DATA_DIRUse a different Chrome data folder, such as Chrome Beta or a Chrome you started yourself

State, logs, the stable copy setup installs (~/.predev/mcp/app), and the saved key are kept in ~/.predev/mcp/.

To turn access off, run stop or turn remote debugging off at chrome://inspect/#remote-debugging. To remove everything, run uninstall.

Safety

Browser Agents Local drives your real, signed-in Chrome. Read this before you turn it on.

  • Anything you can do in a tab, the agent can do. Connect only agents you trust, and watch what they do on sensitive sites. chrome_eval runs JavaScript in the page.
  • Passwords stay with you. It refuses to type into password fields, except on localhost and .test development sites, and masks password values in snapshots.
  • It listens only on your computer. The background process binds to 127.0.0.1, requires a random per-run token stored in a file only you can read, and rejects any request that comes from a web page.
  • Page text leaves your computer only for plain-words actions. chrome_act and chrome_wait conditions send the page text they need to pre.dev. Nothing else does.

Troubleshooting

You seeDo this
Chrome remote debugging is offOpen chrome://inspect/#remote-debugging in Chrome and turn it on
Chrome is asking Allow remote debugging?Click Allow in Chrome, then ask your agent to try again
Chrome asks to allow againNormal after Chrome restarts. Updates keep the approved connection, except a rare one that changes how the background process talks to Chrome
Plain-words actions need a pre.dev account, or a cloud tool says it needs a free pre.dev accountRun npx -y @predotdev/mcp login. No restart needed
A cloud tool says it needs a pre.dev planYour account’s plan does not include the cloud tools. See plan access; your agent can open the subscribe link in your Chrome
pre.dev rejected the saved key, or a plain-words action returns 401Run npx -y @predotdev/mcp login again. If the agent sets PREDEV_API_KEY, update it there too, since it overrides the saved key
The agent cannot start the server, or npx or node is not foundRun setup: it registers full paths that work in desktop apps
Another server already uses the name predevSetup leaves it alone and registers this one as pre-dev
You had the hosted pre.dev MCP or an older Browser Agents Local install (chrome or predev-chrome)Setup replaced it. This server carries all of its tools
Codex says a tool call timed outRun setup, which sets tool_timeout_sec = 900, or set it in ~/.codex/config.toml
A plain-words action returns 402 with subscription_requiredThe free plan’s 10 credits of plain-words actions are used up. Subscribe with the link in the error; your agent can open it in your Chrome
A plain-words action returns 402 with insufficient_creditsYour workspace is out of credits. Open the link in the error: on the free plan, subscribe; on a paid plan, add credits or turn on auto-recharge
A plain-words action returns 429, rate limited or busyWait a few seconds and retry, or use chrome_snapshot refs with chrome_click and chrome_type
Anything elseRun the setup check and read ~/.predev/mcp/predev-mcp.log

Platform support

macOS is supported and tested. Linux and Windows are not tested yet: the server looks for Chrome’s data in the standard places, and on those systems a profile needs an open Chrome window before the agent can use it. Reports and pull requests are welcome on GitHub.

Was this page helpful?

On this page