Docs

Add Browser MCP to Claude Code

Q: How do I add an MCP server to Claude Code?

Run claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest. That is Claude Code's built-in command for registering an MCP server, so no manual JSON is required. Restart Claude Code afterward so it picks up the new server.

Q: Does it only work with Claude Code, or also Cursor / VS Code?

Any MCP client that can run local stdio servers. npx @agent360/browser-mcp install registers the server with Claude Code, Codex, VS Code and Cursor if it finds them. For another client, add the server in its own MCP settings. Clients that read the common mcpServers format take this block; others use their own format (VS Code, for one, uses the root key servers; see the VS Code guide), so follow the client's own MCP guide: ```json {"mcpServers": {"browser-mcp": {"command": "npx", "args": ["@agent360/browser-mcp@latest"]}}} ```

Give Claude Code control of your real, already-logged-in Chrome - four steps. 40 browser tools, your actual cookies and sessions, works on 2FA and CAPTCHA-gated sites where headless tools (Playwright, Puppeteer) get blocked. MIT-licensed, free, and runs on your machine - no account, no telemetry, nothing sent to us.

Two halves, both required

The Chrome extensionAdd to Chrome

The server, in your client

claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest

Then sayOpen example.com and take a screenshot.

You need: Chrome, and Node.js 20 or newer for npx (node -v shows your version) and the claude command (Claude Code itself).

The whole thing, in four steps

1 - Install the Chrome extension. One click from the Chrome Web Store; Chrome keeps it updated. No store? The unpacked install is further down.

2 - Add the MCP server. Paste this in a terminal. Required - the extension does nothing on its own:

claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest

3 - Restart Claude Code. That is what starts the server. The extension shows no badge until step 4 - the server only takes a port the first time your agent actually uses the browser. A green badge with the number of connected agents appears then; nothing on the icon before that is normal. (The icon itself never changes colour - it is the badge that turns green.)

4 - Say this, to check it worked. Paste it to Claude Code:

Open example.com and take a screenshot.

You get an image back instead of "I don't have browser access". That's it - you're running.

Using Cursor, VS Code, Codex or Windsurf instead? Same server, that client's own config - guides here. The rest of this page is the long version, plus what to say next.

Step-by-step install (Claude Code)

Why two steps? Browser MCP is two halves and both are required: a Chrome extension that drives the browser, and a local MCP server that Claude Code talks to. Chrome forbids extensions installing themselves from npm, and npm cannot install a Chrome extension - so neither half can install the other. If you already have the extension (e.g. from the Chrome Web Store), you still need Step 1; if you only run Step 1, you still need Step 2.

Step 1 - Register the MCP server with Claude Code

claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest

That is Claude Code's own MCP command, so the entry lands in the config Claude Code actually reads. --scope user makes Browser MCP available in every project instead of just the current directory; drop it if you only want it here.

Prefer to edit the config by hand? Add this to ~/.claude.json:

{
  "mcpServers": {
    "browser-mcp": {
      "command": "npx",
      "args": ["@agent360/browser-mcp@latest"]
    }
  }
}

The @latest matters: it is what makes the server update itself on every run.

If you want the extension files on disk too (for the unpacked install in Step 2), run:

npx @agent360/browser-mcp install

It copies the extension to ~/.browser-mcp/extension/ and prints the path - copy it, you'll need it in Step 2. Do not rely on it to configure Claude Code; use the claude mcp add command above for that.

Step 2 - Load the extension in Chrome

Chrome doesn't let extensions install themselves from npm, so this one step is manual:

Open Chrome and go to chrome://extensions
Toggle Developer mode ON (top right)
Click Load unpacked (top left, next to "Pack extension")
Navigate to ~/.browser-mcp/extension/ and select it
Mac: in the file picker, press Cmd+Shift+G, paste ~/.browser-mcp/extension/, hit Enter
Windows: paste %USERPROFILE%\.browser-mcp\extension\ into the address bar
Linux: type ~/.browser-mcp/extension/ into the path field

Don't want Developer mode on? Use the Chrome Web Store install instead - see below.

Step 3 - Restart Claude Code

Restart Claude Code so it picks up the new MCP server. The extension stays quiet until your agent first uses the browser; then a green badge with the number of connected agents appears on its icon. 40 browser tools are now available in any Claude Code conversation.

Verify it's working

Paste this to Claude Code:

Open example.com and take a screenshot.

If you get an image back instead of "I don't have browser access", both halves are talking to each other. That is the whole test.

Now what - things to actually say

Nothing happens until you ask, and the hardest part of a new tool is knowing what to ask for. Start with these:

Open Gmail and tell me who sent my last 3 emails.

The one that shows the difference - it works because it is your browser, already signed in. A fresh headless browser would hit a login wall here.

Go to my analytics dashboard, pull this month's numbers, and put them in a table.

A dashboard you are signed into in this Chrome. No API key, no export, no integration to build first.

Where a prompt says example.com, put your own site.

Fill in the signup form at example.com/signup with my details. Stop and ask me before anything sensitive.

You stay in the loop - the agent can pause and ask you before passwords, payment details, or anything it should not decide alone.

Log me in at app.example.com. If it emails a code, open Gmail, read the code and continue.

The move that needs no email-API setup: it opens your Gmail, reads the one-time code and finishes the sign-in.

Walk through my app's signup flow as a real user and tell me where it breaks.

End-to-end QA of your own product, in the same browser your users have.

The pattern: many of the browser tasks you would do yourself, on sites you are already signed into. It is strongest where there is no API - internal dashboards, admin panels, portals, LinkedIn. More examples.

Alternative installs

No npm? Manual zip download

Download the extension zip from the latest GitHub release
Unzip it anywhere (e.g. ~/Downloads/browser-mcp-extension/)
Follow Step 2 above, but select the unzipped folder instead of ~/.browser-mcp/extension/
Wire up Claude Code manually - add this to ~/.claude.json:

{
  "mcpServers": {
    "browser-mcp": {
      "command": "npx",
      "args": ["@agent360/browser-mcp@latest"]
    }
  }
}

Or skip the manual JSON entirely and let Claude Code write it:

claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest

No Developer mode - Chrome Web Store

Install from the Chrome Web Store →

No Developer mode toggle needed, and Chrome updates the extension automatically in the background. This replaces Step 2, not Step 1 - the store hands you the extension, and the extension still needs a server to talk to. So run:

claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest

That registers the server and leaves your store-installed extension alone. Restart Claude Code afterwards.

Installed from the store and the icon says "Not connected"? That is Step 1 missing - not a bug. Run the command above and restart Claude Code. It still says "Not connected" until you ask Claude to use the browser once - that first call is what starts the connection.

What your agent can do

The 2FA killer move

This is the reason people install Browser MCP: Claude Code hits a login wall, needs a verification code, and - because it's driving your actual logged-in Chrome rather than a fresh headless session - it can open your Gmail, read the code, and finish the sign-in itself. There is no email API to set up and no "read my 2FA code" endpoint to call. It works because Browser MCP isn't simulating a browser, it's operating yours: your cookies, your sessions, your already-passed 2FA challenges.

The same real-session advantage is why it works on 2FA- and CAPTCHA-gated sites that block Playwright and Puppeteer - it is not a fresh anonymous session, it is yours. (We do not build detection-evasion; see when-not-to-use.)

40 tools

Category	Tools
Navigation & content	`browser_navigate`, `browser_get_page_content`, `browser_screenshot`, `browser_execute_script`, `browser_extract_list`
Interaction	`browser_click`, `browser_double_click`, `browser_right_click`, `browser_click_xy`, `browser_fill`, `browser_press_key`, `browser_scroll`, `browser_wait`, `browser_hover`, `browser_select_option`, `browser_set_combobox`, `browser_set_date`, `browser_dismiss_overlays`, `browser_handle_dialog`
Tabs & frames	`browser_list_tabs`, `browser_switch_tab`, `browser_close_tab`, `browser_get_new_tab`, `browser_list_frames`, `browser_select_frame`
Data & network	`browser_get_cookies`, `browser_set_cookies`, `browser_get_local_storage`, `browser_set_local_storage`, `browser_fetch`, `browser_wait_for_network`, `browser_extract_token`, `browser_console_logs`, `browser_upload_file`, `browser_drop_file`
CAPTCHA assistance	`browser_solve_captcha` - detects reCAPTCHA v2/v3, hCaptcha, Turnstile and FunCaptcha; the agent can try the reCAPTCHA checkbox, click reCAPTCHA grid cells it chooses, or ask you to solve it with `browser_ask_user`, one step per call. No third-party solving service
Human-in-the-loop	`browser_ask_user` - a card you can drag aside while you log in or solve a CAPTCHA, or a dialog with fields for a 2FA code, right inside the page
Meta & recovery	`browser_about` - version and links to report a bug or wish · `browser_provide_feedback` - checks the install and drafts an issue · `browser_reattach_debugger` - recovery when actions start timing out

Full source: github.com/Agent360dk/browser-mcp.

How this differs from Playwright MCP

Feature	Browser MCP	Playwright MCP
Browser	Your real Chrome, always	Its own browser by default. Your real Chrome too, via their Chrome extension
Logins/cookies	Your existing session	A persistent profile keeps logins between runs, or your own session via their extension
2FA / CAPTCHA-gated sites	Works, and `browser_ask_user` can ask you for the code mid-run	Reachable in extension mode, but nothing can ask you for a code
Human-in-the-loop	`browser_ask_user` pauses, asks you for a code, and continues in the same tab	None. 72 tools, none of which can ask the person anything (checked 2026-09-19)
Several agents at once	20 concurrent, color-coded tab groups	Also supported via their extension: one tab group per connected client
Provider integrations	9 built-in (Stripe, HubSpot, Slack, Shopify, Pipedrive, Calendly, Mailchimp, Google, LinkedIn)	None
Install	`npx @agent360/browser-mcp install`	`npx @playwright/mcp`

Corrected 2026-09-19. Four rows in this table used to say Playwright MCP was headless, made you log in every time, was frequently blocked on 2FA sites, and could only run one session. All four were wrong: Microsoft ships a Chrome extension that uses your own logged-in browser, and their own README documents several clients connected at once, each with its own coloured tab group. We had corrected this in the main README on 2026-09-07 and did not carry the fix across to these pages. The row that survives is human-in-the-loop, and it is measured, not assumed.

Running more than one Claude Code conversation at once

Each conversation gets its own MCP server, which takes its own port (9876-9895) once it first uses the browser, and the extension keeps every session's tabs in a separate color-coded Chrome tab group - one conversation can't see or click another's tabs. Idle sessions auto-exit after 4 hours without commands.

FAQ

How do I add an MCP server to Claude Code? Run claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest. That is Claude Code's built-in command for registering an MCP server, so no manual JSON is required. Restart Claude Code afterward so it picks up the new server.

What is Browser MCP? An MCP (Model Context Protocol) server that gives Claude Code - or any MCP client that can run local stdio servers, including Cursor and VS Code agent mode - control of your actual, already-logged-in Chrome: your cookies, your sessions, your 2FA. 40 tools, MIT-licensed, runs on your own machine.

Is it free? Yes. MIT license, no account, no paid tier.

Does it only work with Claude Code, or also Cursor / VS Code? Any MCP client that can run local stdio servers. npx @agent360/browser-mcp install registers the server with Claude Code, Codex, VS Code and Cursor if it finds them. For another client, add the server in its own MCP settings. Clients that read the common mcpServers format take this block; others use their own format (VS Code, for one, uses the root key servers; see the VS Code guide), so follow the client's own MCP guide:

{"mcpServers": {"browser-mcp": {"command": "npx", "args": ["@agent360/browser-mcp@latest"]}}}

Why do I have to load the extension manually instead of it just installing? Chrome blocks extensions from self-installing from npm or any script - that's a Chrome security boundary, not a Browser MCP limitation. Loading unpacked once, or installing from the Chrome Web Store, are the only two ways in.

Does my browsing data leave my machine? Not to us. The MCP server runs locally over stdio, talks to the extension over a local WebSocket, and the extension talks to Chrome through Chrome's own APIs. What your agent reads goes to your AI client and on to its model provider, like anything else you show it - there is no Agent360 server.

How do I update it? The MCP server updates itself - every Claude Code session runs npx @agent360/browser-mcp@latest (note the @latest in your config), so there's nothing to do. The extension auto-updates only if you installed it from the Chrome Web Store; if you loaded it unpacked, re-run npx @agent360/browser-mcp install and click ↻ reload on chrome://extensions.

Chrome extension says "not connected" - what do I check? First: did you register the MCP server, not just install the extension? If you got the extension from the Chrome Web Store and never added the server to your MCP config, that is the whole problem - the extension has nothing to connect to. Run claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest and restart Claude Code. If the server is configured, confirm the extension is loaded under chrome://extensions, click the extension icon → "Reconnect," and give it 2-3 seconds - it scans ports 9876-9895 for the running server. Still stuck: troubleshooting.

Is this the same as browsermcp.io? No - different project, same underlying idea (MCP + your real Chrome), separate codebase. If you found this page searching generically for "browser mcp," make sure you're grabbing the one you meant: this one is @agent360/browser-mcp on npm, github.com/Agent360dk/browser-mcp on GitHub.

Can I run it across multiple Claude Code conversations at once? Yes - up to 20 concurrent sessions, each on its own port with its own color-coded Chrome tab group, so sessions can't see or control each other's tabs.