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.

Source on GitHub

predotdev/mcp, MIT licensed. On npm as @predotdev/mcp.

Cloud Browser Agents

Run tasks on pre.dev’s browsers through REST, the SDKs, or the hosted MCP server.

Cloud or Local

	Cloud	Local
Browser	pre.dev’s browsers	Your own Chrome, every profile
How it runs	You send a task and a URL by REST, the SDKs, or the browser_agent MCP tool, and get structured data back	Your coding agent drives Chrome step by step with the chrome_* tools
Sites	Public pages; no persistent login profiles	Accounts you are already signed in to: dashboards, internal tools, anything behind a login
Scale	Many tasks in parallel	One Chrome on your computer, shared by all your agents
Setup	None	One command, setup, for every agent on your Mac, or /chrome in the pre.dev CLI
Credits	Per task	Only 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:

1. 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.

2. 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.

3. 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.

4. 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 Code

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

Codex

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

Cursor

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

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

Windsurf

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" }
    }
  }
}

VS Code

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" }
    }
  }
}

Gemini CLI

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

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

OpenCode

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
    }
  }
}

Claude Desktop

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

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

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.

Other clients

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.

No MCP

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>.

Command	What it does
setup	Sign in, add the server to every coding agent on your Mac, and connect to Chrome. Run it again to update to the newest version
check	Check your setup, list your Chrome profiles, and check your key
login	Sign in to pre.dev again. Agents use the new key on their next call, with no restart
logout	Forget the saved key
stop	Stop the background process. It starts again on the next tool call
uninstall	Remove the server from every agent setup added it to, stop it, and delete its files and saved key
tools	List 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:

Tool	What it does
chrome_profiles	List your Chrome profiles (name and Google account) and how many tabs each has open
chrome_tabs	List open tabs grouped by profile
chrome_open	Open a URL in any profile, in the background by default so you are not interrupted
chrome_navigate	Load a URL in a tab, or go back, forward, or reload
chrome_snapshot	List the page’s interactive elements as short refs ([e1], [e2], …), including shadow DOM and same-origin iframes
chrome_click	Click by ref, CSS selector, visible text, or coordinates, with real mouse events
chrome_type	Type into inputs, text areas, rich editors, and dropdowns
chrome_press	Press keys and shortcuts such as Enter, Tab, and cmd+a
chrome_scroll	Scroll the page or bring an element into view
chrome_read	Read a page’s text, a part at a time for long pages
chrome_screenshot	Screenshot the visible area or the full page
chrome_wait	Wait for text, a CSS selector, or a URL change; when you are signed in, wait for a plain-words condition
chrome_eval	Run JavaScript in the page and return the result
chrome_upload	Attach local files to an upload button or file input
chrome_show	Bring a tab to the front so you can watch or take over
chrome_close	Close a tab
chrome_act	Click 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 <[e-mail]> · Create your account
https://example.com/signup
[e1] textbox "Full name"
[e2] textbox "Email" value="[e-mail]"
[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:

Variable	What it does
PREDEV_API_KEY	A workspace API key (pdk_…). Overrides the saved key
PREDEV_API_URL	The pre.dev API to call. Default https://api.pre.dev
PREDEV_MCP_CLOUD	off lists only the Chrome tools, without pre.dev’s cloud tools
CHROME_MCP_USER_DATA_DIR	Use 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 see	Do this
Chrome remote debugging is off	Open 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 again	Normal 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 account	Run npx -y @predotdev/mcp login. No restart needed
A cloud tool says it needs a pre.dev plan	Your 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 401	Run 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 found	Run setup: it registers full paths that work in desktop apps
Another server already uses the name predev	Setup 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 out	Run setup, which sets tool_timeout_sec = 900, or set it in ~/.codex/config.toml
A plain-words action returns 402 with subscription_required	The 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_credits	Your 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 busy	Wait a few seconds and retry, or use chrome_snapshot refs with chrome_click and chrome_type
Anything else	Run 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.