Browser Agents Local

Browser Agents Local is the local edition of Browser Agents: a free, open-source MCP server that 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 works with any MCP client that runs local servers: Claude Code, Codex, Cursor, Windsurf, VS Code (Copilot agent mode), Gemini CLI, OpenCode, Claude Desktop, and others. 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.

Source on GitHub

predotdev/chrome-mcp, MIT licensed.

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 hosted MCP tool, and get structured data back	Your coding agent drives Chrome step by step with MCP 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
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.

Quick start

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

npx -y github:predotdev/chrome-mcp setup

It walks you through everything:

Your browser opens pre.dev with a short code. Sign in, or create a free account, and approve Sign in to pre.dev Browser Agents Local. Setup saves your workspace API key for every agent, so there is nothing to copy.

Add it to every coding agent on your Mac

Setup installs a stable copy and registers it, with full paths that also work in desktop apps, in each agent it finds: Claude Code, Codex, Cursor, Windsurf, VS Code, Gemini CLI, OpenCode, and Claude Desktop. Codex gets a 120-second tool timeout. If a different server named chrome already exists, setup leaves it alone and registers this one as predev-chrome. It backs up each JSON config once, as <file>.bak-chrome-mcp.

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 github:predotdev/chrome-mcp setup` with a 10 minute timeout and tell me what to click.

Setup is safe to run again, and running it again updates to the latest version. Chrome asks Allow remote debugging? once each time it starts, and again after an update.

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 the command npx -y github:predotdev/chrome-mcp. A key is needed only for plain-words actions. Sign in once with npx -y github:predotdev/chrome-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 chrome -e PREDEV_API_KEY=your_key -- npx -y github:predotdev/chrome-mcp

codex mcp add chrome --env PREDEV_API_KEY=your_key -- npx -y github:predotdev/chrome-mcp

Or add this to ~/.codex/config.toml. The longer timeout gives slow pages time to load:

[mcp_servers.chrome]
command = "npx"
args = ["-y", "github:predotdev/chrome-mcp"]
env = { PREDEV_API_KEY = "your_key" }
tool_timeout_sec = 120

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

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

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

{
  "mcpServers": {
    "chrome": {
      "command": "npx",
      "args": ["-y", "github:predotdev/chrome-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": {
    "chrome": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:predotdev/chrome-mcp"],
      "env": { "PREDEV_API_KEY": "your_key" }
    }
  }
}

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

{
  "mcpServers": {
    "chrome": {
      "command": "npx",
      "args": ["-y", "github:predotdev/chrome-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": {
    "chrome": {
      "type": "local",
      "command": ["npx", "-y", "github:predotdev/chrome-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 github:predotdev/chrome-mcp
which node
echo "$(npm root -g)/@predotdev/chrome-mcp/src/bridge.mjs"

Add the chrome 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": {
    "chrome": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/opt/homebrew/lib/node_modules/@predotdev/chrome-mcp/src/bridge.mjs"],
      "env": { "PREDEV_API_KEY": "your_key" }
    }
  }
}

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

Add a local (stdio) server with command npx and arguments -y github:predotdev/chrome-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.

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

Check your setup

npx -y github:predotdev/chrome-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 github:predotdev/chrome-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
`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

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

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

Plain-words actions are the only part of Browser Agents Local that calls pre.dev. Each one costs a small fraction of a credit. Free workspaces get 20 credits of plain-words actions, separate from the AI Gateway trial, which covers more than a thousand actions. 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 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/chrome-mcp/credentials.json, a file only you can read, and every agent uses it. 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`
`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/chrome-mcp/app), and the saved key are kept in ~/.predev/chrome-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	Expected after Chrome restarts or after the server updates
`Plain-words actions need a pre.dev account`	Run `npx -y github:predotdev/chrome-mcp login`. No restart needed
`pre.dev rejected the saved key`, or a plain-words action returns `401`	Run `npx -y github:predotdev/chrome-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
You already have a different server named `chrome`	Setup leaves it alone and registers this one as `predev-chrome`
Codex says a tool call timed out	Run `setup`, which sets `tool_timeout_sec = 120`, or set it in `~/.codex/config.toml`
A plain-words action returns `402` with `subscription_required`	The free plan’s 20 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`	Add credits with the top-up link in the error
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/chrome-mcp/chrome-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.

Source on GitHub

Cloud Browser Agents

​Cloud or Local

​Quick start

​Manual setup

​Check your setup

​Commands

​Tools

​Plain-words actions

​Credits

​Configuration

​Safety

​Troubleshooting

​Platform support

Cloud or Local

Quick start

Manual setup

Check your setup

Commands

Tools

Plain-words actions

Credits

Configuration

Safety

Troubleshooting

Platform support