Claude Desktop browser automation in your own Chrome

Claude Desktop can call any MCP tools you configure. On its own it cannot open your analytics dashboard, check a GitHub settings page that sits behind your login, or read the admin panel your team never built an API for. This guide sets up Claude Desktop browser automation against the Chrome you already use, sessions included, with MCP Browser Extension: a local MCP server (@mehmoodqureshi/chrome-mcp on npm) and a Chrome extension. You will edit one JSON file, install the extension, press one button to pair, allow the sites you want, and run a first task.

If you only want the commands, the quickstart has them on one page.

What you are setting up

Claude Desktop is an MCP host. When it starts, it reads a config file, launches each MCP server listed there as a child process, and offers that server's tools to Claude. A browser MCP server is one whose tools are things like navigate, click, get_text and screenshot.

Many browser MCP servers start a fresh Chromium for the agent. That browser is signed out, so every site asks for a login and often a second 2FA prompt. MCP Browser Extension takes the other route. The server never launches a browser. An MV3 extension inside your normal Chrome connects to the server over a localhost WebSocket and carries out each tool call with Chrome's own extension APIs. A page Claude opens is the page you would see, signed in as you, and no password or cookie goes into a config file. The logged-in Chrome page explains that model, and what an MCP browser extension is compares it with servers that launch their own browser.

Two things follow from this design. The extension is required: without it, no tool can run. And the browser is a real, visible Chrome window, not a headless one, so this is for work on your own machine rather than CI.

Before you start, check that you have Node 18 or newer (node --version) and Chrome 116 or newer.

Step 1: Add the server to claude_desktop_config.json

Claude Desktop keeps its MCP servers in a file called claude_desktop_config.json. You can open it from the app with Settings > Developer > Edit Config, or find it directly:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a chrome-mcp entry under "mcpServers". On macOS it looks like this:

{
  "mcpServers": {
    "chrome-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmoodqureshi/chrome-mcp@latest",
        "--allow-domain",
        "example.com",
        "--enable-mutations",
        "--persist-token"
      ]
    }
  }
}

On Windows, npx is a batch shim (npx.cmd), and MCP hosts start servers without a shell, which cannot run a .cmd file. So "command": "npx" fails to start there. Wrap it in cmd /c instead:

{
  "mcpServers": {
    "chrome-mcp": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@mehmoodqureshi/chrome-mcp@latest",
        "--allow-domain",
        "example.com",
        "--enable-mutations",
        "--persist-token"
      ]
    }
  }
}

No WSL is needed. Native Windows works with that one change.

If the file already has other servers, add chrome-mcp as one more key inside the existing "mcpServers" object rather than pasting a second one. What the arguments do:

• -y lets npx install the package without asking. @latest means you always get the newest release. On top of that, an installed copy checks npm when it starts and runs a newer published version in its place with the same arguments, so a config you wrote months ago keeps working.
• --allow-domain example.com is the allowlist. Replace example.com with the sites you want Claude to use, one --allow-domain pair per site. Step 4 covers the rules.
• --enable-mutations lets Claude navigate, open tabs, click and type. Leave it out and Claude can only read.
• --persist-token keeps the same pairing token across restarts. Pairing survives restarts without it, because the extension fetches a new token by itself, but it does no harm.

Save the file, then fully quit Claude Desktop and open it again. Closing the window is not enough; the app reads MCP servers only when it starts. On that first start the server writes ~/.chrome-mcp/handshake.json with its port and pairing token, and registers a small native messaging helper with Chrome. The helper is what makes the next step one click.

Step 2: Install the Chrome extension

Install MCP Browser Extension from the Chrome Web Store listing. It needs no Developer mode, and Chrome keeps it updated. Store releases go through review, so the extension can lag the npm package by a version. It pairs with any server version and simply skips features that version predates.

There is also a copy bundled in the npm package, unpacked to ~/chrome-mcp-extension (%USERPROFILE%\chrome-mcp-extension on Windows) each time the server boots. That is mainly for people working on the extension itself. It does not update through Chrome, and you should load either it or the store copy in a profile, not both.

Chrome hides new extensions behind the puzzle-piece button next to the address bar. Click it, find MCP Browser Extension and pin it, so its icon and status badge stay in the toolbar.

Step 3: Press Connect

With Claude Desktop running (so the server has started at least once), click the extension's toolbar icon and press Connect in the popup. A fresh install also opens the extension's Settings page, which has the same button.

The first click asks Chrome for one permission: "communicate with cooperating native applications". Allow it. The extension then asks the helper the server registered for the port and token and pairs on its own. There is nothing to copy or paste, and Chrome lets only this extension talk to that helper. If the server later rotates its token, the extension fetches the new one by itself.

The Settings page with sample data. Connect sits at the top. The port and token fields are only for the manual fallback.

From then on the popup is where you check on things. It shows the connection status, whether the site in your current tab is allowed (with an Allow button if it is not), sites that were recently blocked, and your allowed sites. The badge on the icon gives the short version:

If Connect reports a problem, or you run the server with --no-native-host, pair by hand: run npx -y @mehmoodqureshi/chrome-mcp@latest --print-pairing, open the extension's Settings, and paste the port and token from ~/.chrome-mcp/handshake.json. Do not paste that token anywhere else.

Step 4: Decide which sites Claude may use

The server is deny-all by default. With no flags, Claude can read nothing, click nothing, run no eval, download nothing and upload nothing. You open it up deliberately, in one of two ways.

The first is flags in the config. A setup for GitHub, your Vercel previews and a local dev server looks like this (on Windows, keep the cmd and /c form from Step 1):

{
  "mcpServers": {
    "chrome-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@mehmoodqureshi/chrome-mcp@latest",
        "--allow-domain", "github.com",
        "--allow-domain", "*.vercel.app",
        "--allow-domain", "localhost",
        "--enable-mutations",
        "--persist-token"
      ]
    }
  }
}

Flag changes need the same full quit and reopen of Claude Desktop. A few rules:

• *.example.com covers a domain and its subdomains.
• Paste a full URL or a host:port and the scheme, port and path are stripped, so localhost covers every local port. 127.0.0.1 is a different host and needs its own entry.
• Reads are gated, not only clicks, and the extension re-checks the same policy on its side.
• eval, downloads and uploads stay off until you add --unsafe-enable-eval, --enable-downloads or --enable-uploads.

The second way needs no restart. When Claude is refused a site, the toolbar icon shows a ?. Open the popup and press Allow next to the blocked site, or allow the site in your current tab. It applies at once to every session sharing that Chrome and is saved to ~/.chrome-mcp/allowed-sites.json, so it survives restarts. Claude cannot approve a site for itself: the extension refuses every command aimed at its own pages. Sites allowed in the popup can be removed there; sites from --allow-domain stay until you change the flags.

Password field values are never returned, --redact scrubs tokens, API keys and JWTs out of page reads, and every call is logged with its URL and allow or deny verdict. The security page covers all of it.

Step 5: Run a first real task in Claude Desktop

Start a new chat and check the chain first:

Call chrome_status, then tabs_list, and tell me which tabs you can see.

chrome_status should report a connected browser, and tabs_list should list tabs from your real Chrome. If nothing is paired, chrome_status returns a setup list with the exact steps for your case, and Claude should pass those on rather than retry.

Now give it something with a real answer. With github.com allowed:

Open https://github.com/pulls in a background tab and read it.
List the open pull requests I am involved in, with the repository,
title and how long each has been open. Then close the tab.

Claude will usually call tab_new, read the page with read_as_markdown or get_text, and answer from your signed-in view, private repositories included. Notice what it does not do: it works in its own background tab. Calls without a tab id go to the agent's tab, never to the one you are looking at, so you can keep working while it reads. If you do want it to act on your current page, ask it to find that tab with tabs_list and pass its id.

For several pages at once, the batch tool runs many calls in one request, so Claude can open a handful of tabs and read them together. A prompt like "open these four dashboards in background tabs, read each one, and give me a table of the headline numbers" is a good fit. The tools reference lists every tool and its arguments.

Finally, ask Claude to open a site you did not allow. The call should be refused with a message that points to the popup's Allow button. That refusal is the part that makes it safe to leave the setup in place.

Running Claude Desktop and Claude Code side by side

Each MCP host session starts its own server, and they share your Chrome. The first one to start owns the bridge port; later ones join it and relay their calls through it, so Claude Desktop and a Claude Code terminal can both use the same browser without disconnecting each other. Sessions share tabs too, so give each its own tabs rather than having two drive the same page at once. If you use Claude Code as well, the Claude Code setup guide covers its one-line claude mcp add command.

If you would rather not edit anything by hand, the agent setup page has a prompt that an agent with shell access can follow to install the server and wire it into your client. It stops for the steps that must happen inside Chrome.

Troubleshooting

Claude Desktop does not show the tools

The app has not loaded the server. Check that the file is valid JSON (a missing comma or an extra trailing one is the usual cause), that chrome-mcp sits inside "mcpServers", and then fully quit and reopen Claude Desktop. On Windows, confirm the command is cmd with /c as the first argument.

The badge stays grey

The extension is not paired. Make sure Claude Desktop is running so the server has started, then click the toolbar icon and press Connect. If that fails, use the manual pairing fallback from Step 3.

Every call says it is blocked

The site is not on your allowlist. Press Allow in the popup, or add --allow-domain <host> and restart the app. If navigate or tab_new is refused on a site you did allow, --enable-mutations is probably missing.

Claude sees no browser at all

Calls that fail with NO_BACKEND mean no paired browser is available. Ask Claude to call chrome_status and follow the setup steps it returns. They name what went wrong, such as the extension not being installed or paired.

A page shows a sign-in screen

Your session on that site expired. auth_check reports this as [AUTH_REQUIRED] rather than a timeout. Sign in again in the same Chrome and retry. The server never holds credentials or signs in for you; can AI agents log in to websites explains why.

FAQ

Can Claude Desktop control my browser?

Yes, through an MCP server. Add MCP Browser Extension to claude_desktop_config.json, install the Chrome extension and press Connect. Claude can then open tabs, read pages, click and type in your own Chrome, on the sites you allow.

Where is claude_desktop_config.json?

On macOS it is at ~/Library/Application Support/Claude/claude_desktop_config.json, and on Windows at %APPDATA%\Claude\claude_desktop_config.json. In the app, Settings > Developer > Edit Config opens it.

Does Claude Desktop use my existing Chrome logins?

Yes. The extension runs in the Chrome you already use, so any site you are signed into is signed in for Claude too. No cookies or passwords go into the config.

Why does Claude Desktop not see the browser tools after I edit the config?

Claude Desktop loads MCP servers only at startup. Fully quit the app and reopen it. If the tools are still missing, check the JSON for syntax errors and, on Windows, use the cmd /c npx form.

Is this the same as Claude in Chrome?

No. Claude in Chrome is Anthropic's own extension. MCP Browser Extension is a separate open-source MCP server and extension that works with any MCP host, Claude Desktop included. Claude in Chrome vs MCP Browser Extension compares them.