> ## Documentation Index > Fetch the complete documentation index at: https://docs.pre.dev/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 . > 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: 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. Free and open source. 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. `predotdev/chrome-mcp`, MIT licensed. 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: ```bash theme={null} 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. 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 `.bak-chrome-mcp`. 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. ```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. **Or let your agent do it.** Paste this into Claude Code or any coding agent: ```text theme={null} 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](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. ```bash theme={null} claude mcp add --scope user chrome -e PREDEV_API_KEY=your_key -- npx -y github:predotdev/chrome-mcp ``` ```bash theme={null} 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: ```toml theme={null} [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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "servers": { "chrome": { "type": "stdio", "command": "npx", "args": ["-y", "github:predotdev/chrome-mcp"], "env": { "PREDEV_API_KEY": "your_key" } } } } ``` Add this to `~/.gemini/settings.json`: ```json theme={null} { "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: ```json theme={null} { "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: ```bash theme={null} 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: ```json theme={null} { "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 ```bash theme={null} 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 | 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: ```text theme={null} Tab A137CF · Work · 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](/coding-agent/plans-and-credits#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`](/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](/api-reference/errors#ai-gateway-errors); see [troubleshooting](#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](#check-your-setup) 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](https://github.com/predotdev/chrome-mcp). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.