> ## Documentation Index
> Fetch the complete documentation index at: https://predev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agents: start with https://docs.pre.dev/agents.md, which has complete recipes, plan access, polling rules, errors and limits.
> Authenticate with the workspace API key (pdk_…) from Integrations → Built-in, sent as Authorization: Bearer <key>.
> REST API: https://api.pre.dev (OpenAPI: https://docs.pre.dev/api-reference/openapi.json). AI Gateway: https://api.pre.dev/v1, OpenAI-compatible (OpenAPI: https://docs.pre.dev/api-reference/ai-gateway.openapi.json).
> pre.dev MCP server: npx -y @predotdev/mcp setup adds it to every local coding agent with every pre.dev tool plus the user's own Chrome; the hosted server is https://api.pre.dev/mcp. Search these docs over MCP at https://docs.pre.dev/mcp.

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

> [!TIP]
>
> **Coming from Claude in Chrome?** [Switch in two steps](https://predev.mintlify.site/browser-agents/switch-from-claude-in-chrome.md). Your Chrome profiles, tabs, and logins carry over.

> **[Source on GitHub](https://github.com/predotdev/mcp)**
>
> `predotdev/mcp`, MIT licensed. On npm as `@predotdev/mcp`.

> **[Cloud Browser Agents](https://predev.mintlify.site/browser-agents/overview.md)**
>
> 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:

```bash theme={null}
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](https://predev.mintlify.site/cli/overview.md)? 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**

```text theme={null}
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.

> [!NOTE]
>
> **Or let your agent do it.** Paste this into Claude Code or any coding agent:
>
> ```text theme={null}
> 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](https://predev.mintlify.site/cli/overview.md), type:

```text theme={null}
/chrome
```

No CLI yet? Install it with:

```bash theme={null}
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](https://pre.dev/projects/integrations?tab=built-in) 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**

```bash theme={null}
claude mcp add --scope user predev -e PREDEV_API_KEY=your_key -- npx -y @predotdev/mcp
```

**Codex**

```bash theme={null}
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:

```toml theme={null}
[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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

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

**Gemini CLI**

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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**

```bash theme={null}
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**

```bash theme={null}
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](https://github.com/predotdev/mcp#setup-for-every-agent) 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:

```bash theme={null}
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

```bash theme={null}
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](#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](https://predev.mintlify.site/coding-agent/plans-and-credits.md#api-and-mcp-access); see the [MCP tool reference](https://predev.mintlify.site/mcp/tools.md). 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:

```text theme={null}
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](https://predev.mintlify.site/coding-agent/plans-and-credits.md#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`](https://predev.mintlify.site/ai-gateway/api/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](https://predev.mintlify.site/api-reference/errors.md#ai-gateway-errors); see [troubleshooting](#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](https://predev.mintlify.site/coding-agent/plans-and-credits.md#api-and-mcp-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](#check-your-setup) 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](https://github.com/predotdev/mcp).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.