chrome-mcp

One MCP server gives your coding agent everything pre.dev does:

• Browser Agents Local: your own Chrome. Open a tab in your work profile, read a dashboard you are already logged into, fill in a form, click through a flow and screenshot the result, all in the Chrome you use every day. No second browser, nothing to log into again, no cookies copied anywhere.

• Browser Agents in the cloud. Send a URL and a task to pre.dev's browsers and get structured data back, many runs in parallel.

• Specs and plans. Plan an app or feature before building it: architecture, tech stack, milestones and user stories.

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

Built with the pre.dev CLI.

Quick start

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

npx -y @predotdev/mcp setup

It walks you through everything:

1. Signs you in to pre.dev in your browser (or creates a free account). Approve, and your key is saved for every agent. Nothing to copy. Already signed in to the pre.dev CLI? It uses that login.

2. Adds it to every coding agent on your Mac: Claude Code, Codex, Hermes, Pi, OpenClaw, Cursor, Copilot CLI, Cline, Antigravity, Gemini CLI, OpenCode, VS Code, Claude Desktop, the pre.dev CLI and more (28 in all; list). Already using the hosted pre.dev MCP? This one includes all of its tools, so setup replaces it.

3. Connects to Chrome. The first time, it asks you to turn on remote debugging at chrome://inspect/#remote-debugging (it copies the address for you), and Chrome asks "Allow remote debugging?": click Allow.

Then restart your agent and try:

List my Chrome profiles and the tabs I have open.

The command is safe to run again at any time, and running it again updates to the latest version. npx -y @predotdev/mcp check shows the state of everything, and uninstall removes it from every agent.

Coming from Claude in Chrome?

Run the setup command above, then type /chrome in Claude Code and turn off Enabled by default (or start a session with claude --no-chrome). Your Chrome profiles and logins carry over, because this server drives the Chrome you already use. The switching guide maps each Claude in Chrome tool to its pre.dev tool and has a line you can paste into CLAUDE.md.

Related MCP server: byob

Local or cloud?

Both editions of pre.dev Browser Agents are in this server, and your agent picks per task.

What your agent can do

In your own Chrome (run on your Mac):

In pre.dev's cloud (need a pre.dev plan; on the free plan your agent sees them and can open the subscribe page for you):

This is what your agent sees when it takes a snapshot:

Tab A137CF · Work <you@company.com> · Create your account
https://example.com/signup
Headings: "Create your account"
Scroll: 0/640px
[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"

Every tab is labeled with the profile it belongs to, so the agent always knows which account it is acting as.

Plain-words actions

Once you are signed in to pre.dev (setup or login does it, or set PREDEV_API_KEY), two things turn on:

• chrome_act: click or type into an element described in plain words, like "the Create button in the dialog", in under a second with no snapshot needed. If it isn't sure, it lists the likely matches instead of guessing.

• chrome_wait with condition: wait until a plain-words statement about the page is true, like "the export has finished".

Pricing. The MCP server is free and open source, and the Chrome tools run free on your Mac. Plain-words actions and the cloud tools use pre.dev credits, the same credits as the rest of pre.dev (pricing). Each action costs a small fraction of one credit, and the free trial's credits cover hundreds of them. They show up in your usage as browser-agents-local, and check shows your plan. If the free plan's allowance or your credits run out, your agent tells you and offers to open the billing page in your Chrome; everything else keeps working. Every other tool runs entirely on your machine and never calls pre.dev.

Setup for every agent

setup does this for you. To add it by hand instead (for example to an agent setup doesn't know), every agent runs the same command. Sign in once with npx -y @predotdev/mcp login and leave the key out, or put your key from Integrations → Built-in in the agent's environment:

npx -y @predotdev/mcp        env: PREDEV_API_KEY=your_key   (optional after login)

setup finds and configures each of these that is installed: Claude Code, Codex, Hermes, Pi, OpenClaw, Cursor (editor and CLI), Windsurf, GitHub Copilot CLI, Antigravity, Gemini CLI, Cline, Kiro, Qwen Code, Factory Droid, Augment, Amp, Kilo Code, Kimi Code, Junie, Warp, Rovo Dev, OpenHands, LM Studio, OpenCode, VS Code, VS Code Insiders, Claude Desktop and the pre.dev CLI. Devin CLI, Grok Build and Warp also read Claude Code's or Cursor's config, so they pick it up from there. Zed's settings file usually has comments, so setup leaves it to you (below).

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

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. The longer timeout gives specs and cloud runs time to finish. In a running chat, /reload-mcp picks it up.

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

pi mcp list should say 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 (setup writes it for you).

In the pre.dev CLI, type /chrome (and /chrome off to turn it off). The CLI has pre.dev's cloud tools built in, so it only needs the Chrome tools, and the server uses your pre.dev CLI login. /chrome and setup both add this to ~/.predev/mcp.json:

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

The agent sees the tools as predev_chrome_open, predev_chrome_act and so on.

From the pre.dev CLI, predev mcp setup runs this package's setup for your other agents.

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 to ~/.cursor/mcp.json, then restart Cursor:

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

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

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

Add 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 to ~/.gemini/settings.json:

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

Add to ~/.config/opencode/opencode.json:

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

Desktop apps don't load your shell's PATH, so give them full paths. Install once:

npm install -g @predotdev/mcp

Then print the exact entry to paste:

echo "\"predev\": {\"command\": \"$(which node)\", \"args\": [\"$(npm root -g)/@predotdev/mcp/src/bridge.mjs\"], \"env\": {\"PREDEV_API_KEY\": \"your_key\"}}"

Put that entry inside "mcpServers" in ~/Library/Application Support/Claude/claude_desktop_config.json, replace your_key, then restart Claude Desktop. The same trick works for any app that says it can't find npx or node.

Every entry below is the same server: command npx, arguments -y @predotdev/mcp.

In ~/.config/zed/settings.json:

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

In ~/.config/goose/config.yaml, under extensions::

  predev:
    type: stdio
    name: predev
    enabled: true
    cmd: npx
    args: [-y, "@predotdev/mcp"]
    envs: {}
    timeout: 900

For one session only: goose session --with-extension "npx -y @predotdev/mcp".

Continue, in ~/.continue/config.yaml:

mcpServers:
  - name: predev
    command: npx
    args: ["-y", "@predotdev/mcp"]

Crush, one line in ~/.config/crush/crushrc:

mcp add predev --command npx --args -y --args @predotdev/mcp

Mistral Vibe, in ~/.vibe/config.toml:

[[mcp_servers]]
name = "predev"
transport = "stdio"
command = "npx"
args = ["-y", "@predotdev/mcp"]

Every tool also runs from a shell, so any agent that can run commands can drive your Chrome:

npx -y @predotdev/mcp tools                       # list the tools and their arguments
npx -y @predotdev/mcp call chrome_open '{"profile":"Personal","url":"https://example.com"}'
npx -y @predotdev/mcp call chrome_snapshot '{"tab":"A1B2C3"}'
npx -y @predotdev/mcp call chrome_click '{"tab":"A1B2C3","ref":"e4"}'

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. Point your agent at this section, or paste npx -y @predotdev/mcp tools into its instructions.

Add a local (stdio) server with command npx, arguments -y @predotdev/mcp, and the environment variable PREDEV_API_KEY. If the client can't find npx, use the full-path setup from the Claude Desktop section.

How it works

flowchart LR
  A["Claude Code"] --> D
  B["Codex"] --> D
  C["Cursor"] --> D
  D["pre.dev MCP background process<br/>(one per Chrome)"] -- "one approved connection" --> E["Your Chrome<br/>(every profile)"]
  D -. "plain-words actions and cloud tools" .-> F["pre.dev API"]

• Chrome asks you to approve each debugging connection. Instead of every agent opening its own connection (and its own prompt), the first agent starts a small background process that holds one connection, and every agent talks to it. You click Allow once each time Chrome starts.

• Each agent uses its own pre.dev API key, even though they share the connection.

• The cloud tools are pre.dev's hosted MCP tools, passed through on the same key, so they stay current without updating this package.

• Tabs open in the background by default and are kept responsive while an agent works in them, so you can keep using Chrome.

• Snapshots reach into shadow DOM and same-origin iframes, and clicks are real mouse events, so modern web apps behave the way they do for you.

• It has no dependencies: plain Node.js talking to Chrome's DevTools Protocol.

Safety

This tool drives your real, logged-in Chrome. Read this before you turn it on.

• Anything you can do in a tab, the agent can do. Only connect agents you trust, and keep an eye on what they do on sensitive sites. chrome_eval runs JavaScript in the page. A page can contain text written to steer an agent; the agent is told to treat page content as data, not instructions, but watch what it does after reading sites you don't trust.

• Passwords stay with you. It refuses to type into password fields (except on localhost and .test dev sites) and masks the values of password, card number, security code, one-time code and other secret-looking fields in snapshots. It won't attach or open SSH keys, cloud credentials, .env files, your saved pre.dev key or Chrome's own data files. The agent is told never to enter passwords, payment details or government ID numbers.

• It only listens on your machine. The background process binds to 127.0.0.1 only and rejects requests without a random per-run token, which is stored in a file only you can read. It also rejects any request that comes from a web page.

• What leaves your machine. Plain-words actions send pre.dev what that one action needs, and pre.dev's AI model reads it to answer: chrome_act sends your description, the page's headings and its interactive elements (role, name and field value, with the secret fields above masked); a plain-words chrome_wait sends the condition, the page title, its URL (with token-like query values removed), the interactive elements and up to about 8,000 characters of the page's visible text. The cloud tools send what you ask them to do. Every other Chrome tool runs locally, though your agent's own AI model sees what the tools return.

• Off switch. Run npx -y @predotdev/mcp stop to stop the background process, or turn remote debugging off at chrome://inspect/#remote-debugging.

Configuration

Set these in your agent's MCP config (env).

State, logs, the stable copy setup installs and the key saved by login (readable only by you) are kept in ~/.predev/mcp/.

Commands

npx -y @predotdev/mcp setup      # sign in, add to every agent, connect to Chrome (also updates)
npx -y @predotdev/mcp check      # check your setup, list your Chrome profiles, check your key
npx -y @predotdev/mcp login      # sign in to pre.dev again
npx -y @predotdev/mcp logout     # forget the saved key
npx -y @predotdev/mcp stop       # stop the background process (it restarts on the next tool call)
npx -y @predotdev/mcp uninstall  # remove it from every agent and delete its files

Troubleshooting

Platform support

macOS is supported and tested. Linux and Windows are not tested yet. The code looks for Chrome's data in the standard places (~/.config/google-chrome and %LOCALAPPDATA%\Google\Chrome\User Data), and on those systems a profile needs an open Chrome window before the agent can use it. Reports and pull requests are welcome.

Development

git clone https://github.com/predotdev/mcp
cd mcp
node src/bridge.mjs check

Point your agent at node /path/to/mcp/src/bridge.mjs. Edits to src/tools.mjs reload automatically without dropping Chrome's approved connection. Edits to src/bridge.mjs restart the background process, so Chrome asks you to allow again.

About

Free and open source from pre.dev, built with the pre.dev CLI. Try it on your own project:

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

Want the same browser agents from your own code? Use the REST API and SDKs.

MIT licensed. See LICENSE.