{ "markdown": "# Browser MCP by [Agent360](https://agent360.dk)\n\n[![npm version](https://img.shields.io/npm/v/@agent360/browser-mcp)](https://www.npmjs.com/package/@agent360/browser-mcp)\n[![npm downloads](https://img.shields.io/npm/dw/@agent360/browser-mcp)](https://www.npmjs.com/package/@agent360/browser-mcp)\n[![GitHub stars](https://img.shields.io/github/stars/Agent360dk/browser-mcp)](https://github.com/Agent360dk/browser-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)\n[![Chrome Web Store](https://img.shields.io/badge/Chrome_Web_Store-live-green)](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl)\n\n**Your AI agent drives your real, logged-in Chrome — and works where headless tools die.**\n\n[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000?logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=browser-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAYWdlbnQzNjAvYnJvd3Nlci1tY3BAbGF0ZXN0Il19)\n[![Add to VS Code](https://img.shields.io/badge/Add%20to-VS%20Code-0098FF?logo=visualstudiocode)](vscode:mcp/install?%7B%22name%22%3A%22browser-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40agent360%2Fbrowser-mcp%40latest%22%5D%7D)\n[![Glama quality](https://glama.ai/mcp/servers/Agent360dk/browser-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Agent360dk/browser-mcp)\n\n[![Browser MCP Demo](assets/demo.gif)](https://browsermcp.dev)\n\n▶ **[Watch the 37-second demo with sound →](https://browsermcp.dev)**\n\nBrowser MCP gives Claude Code (and any MCP client — Cursor, VS Code agent mode) control of your actual Chrome: your cookies, your sessions, your 2FA. So it works on CAPTCHA, 2FA and anti-bot sites where Playwright and Puppeteer get blocked — because it's *you* browsing.\n\nThe killer move: it hits a login wall, reads the verification code from your own Gmail tab, and continues the sign-in. No API can do that. Operate platforms with no API, QA your own web app end-to-end, or work dashboards, LinkedIn and Reddit at human pace — with you approving the sensitive steps.\n\n40 tools. Auto-clicks the reCAPTCHA v2 checkbox, with a human fallback for the rest. Multi-session color-coded tab groups. **MIT, free, and 100% local — nothing leaves your machine.**\n\n## The whole thing, in four steps\n\n**1 — Install the Chrome extension.** One click from the [Chrome Web Store](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl); Chrome keeps it updated. No store? See the unpacked install below.\n\n**2 — Add the MCP server.** Paste this in a terminal. Required — the extension does nothing on its own:\n\n```bash\nclaude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest\n```\n\n**3 — Restart Claude Code.** That is what starts the server. The extension icon turns green.\n\n**4 — Say this, to check it worked.** Paste it to Claude Code:\n\n> Take a screenshot of my current Chrome tab.\n\nYou get an image back instead of *\"I don't have browser access\"*. **That's it — you're running.** → [What else to say](#youre-in-now-what)\n\nUsing Cursor, VS Code, Codex or Windsurf? Same server, that client's own config — see [browsermcp.dev/docs](https://browsermcp.dev/docs/install-cursor/). Everything below is the long version.\n\n## The long version — install, step by step\n\n> **Browser MCP is two halves and you need both:** a **Chrome extension** (drives the browser) and a **local MCP server** (what your agent actually talks to). Installing only the extension — e.g. straight from the Chrome Web Store — leaves it stuck on *\"Not connected\"*, because there is no server for it to reach. Chrome cannot install the server, and npm cannot install the extension. Hence two steps.\n\n### Step 1: Register the MCP server with Claude Code\n\n```bash\nclaude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest\n```\n\nThat is Claude Code's own MCP command, so the entry lands in the config Claude Code actually reads. `--scope user` makes it available in every project.\n\nWant the extension files on disk for the unpacked install in Step 2? Also run:\n\n```bash\nnpx @agent360/browser-mcp install\n```\n\nIt copies the extension to `~/.browser-mcp/extension/` and **prints that path in the terminal — copy it.** (Use it for the extension files only; register the server with `claude mcp add` above.)\n\n### Step 2: Load the extension in Chrome\n\n> Chrome won't let extensions install themselves from npm — you load it manually one time. To **update** later, re-run the install command and reload it (see [Keeping it updated](#keeping-it-updated)). Prefer the [Chrome Web Store](#chrome-web-store-one-click-install) install if you'd rather have the extension auto-update.\n\n1. **Open Chrome** and type `chrome://extensions` in the address bar\n2. **Toggle \"Developer mode\"** ON (top right corner)\n3. **Click \"Load unpacked\"** (top left, next to \"Pack extension\")\n4. **Navigate to `~/.browser-mcp/extension/`** and click \"Select\"\n - On Mac: Press `Cmd+Shift+G` in the file picker, paste `~/.browser-mcp/extension/`, press Enter\n - On Windows: Paste `%USERPROFILE%\\.browser-mcp\\extension\\` in the address bar\n - On Linux: Type `~/.browser-mcp/extension/` in the path field\n5. **Restart Claude Code** so it picks up the new MCP server\n\nThat's it. The Browser MCP icon will appear in your toolbar, and 40 browser tools are now available in Claude Code.\n\n### Alternative: Manual zip download (no npm)\n\nIf you don't want to use npm, download the extension directly:\n\n1. [Download the extension zip](https://github.com/Agent360dk/browser-mcp/releases/latest) (`agent360-browser-mcp-.zip`) from the latest GitHub release\n2. Unzip the file (anywhere — e.g. `~/Downloads/browser-mcp-extension/`)\n3. Follow Step 2 above, but select the unzipped folder instead of `~/.browser-mcp/extension/`\n4. Register the server — run `claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest`, or add this to `~/.claude.json` by hand:\n ```json\n {\n \"mcpServers\": {\n \"browser-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"@agent360/browser-mcp@latest\"]\n }\n }\n }\n ```\n\n### Chrome Web Store (no Developer mode, auto-updating extension)\n\n**This replaces Step 2 only — you still need Step 1.**\n\n1. [**Install the extension from the Chrome Web Store →**](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl) — no Developer mode toggle, and Chrome keeps it updated for you.\n2. Register the MCP server:\n ```bash\n claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest\n ```\n (For Cursor / VS Code / Codex, use that client's own MCP config instead — see [browsermcp.dev/docs](https://browsermcp.dev/docs/install-claude-code/).)\n3. Restart Claude Code.\n\nSkip step 2 and the extension icon will sit on **\"Not connected\"** forever — that is the symptom of a missing MCP server, not a broken extension.\n\n## You're in. Now what?\n\nNothing happens until you ask, and the hardest part of a new tool is knowing what to ask for. Paste one of these to your agent:\n\n| Say this | What it shows |\n|---|---|\n| *\"Take a screenshot of my current Chrome tab.\"* | **Start here.** An image back instead of *\"I don't have browser access\"* means both halves are talking. That is the whole install test. |\n| *\"Open my Gmail tab 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 headless tool hits a login wall here. |\n| *\"Go to my analytics dashboard, pull this month's numbers, and put them in a table.\"* | Any dashboard you are already logged into. No API key, no export, no integration to build first. |\n| *\"Fill in this signup form with my details. Stop and ask me before anything sensitive.\"* | You stay in the loop — it hands control back for passwords, payment details, or anything it should not decide alone. |\n| *\"Log me in here. If it emails a code, read it from my Gmail tab and continue.\"* | The move no API can make: it reads the one-time code out of your own inbox and finishes the sign-in. |\n| *\"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. |\n\nThe pattern: **anything you would do yourself in a browser, on a site you are already signed into.** It is strongest where there is no API — internal dashboards, admin panels, portals, LinkedIn. Built something good? [Add it to the gallery](USE_CASES.md).\n\n## Why This Over Playwright MCP / BrowserMCP?\n\n| | Browser MCP | Playwright MCP | BrowserMCP.io |\n|---|---|---|---|\n| **Browser** | Your real Chrome, via extension | Persistent profile by default, or your Chrome via their extension | Your real Chrome |\n| **Maintained** | Actively — latest release v1.29.0 (2026-09-07) | Actively (Microsoft) | Last commit Apr 2025 |\n| **Logins/cookies** | Your existing session | Persistent profile keeps logins between runs | Already authenticated |\n| **Several agents, one logged-in profile** | 20 concurrent, each with its own color-coded tab group | Their docs: concurrent clients on one profile *conflict* — each extra client needs `--isolated` or its own `--user-data-dir` | Single session |\n| **Human-in-the-loop** | `browser_ask_user` — 2FA, CAPTCHA, credential input | None | None |\n| **Provider integrations** | 9 built-in (Stripe, HubSpot, Slack...) | None | None |\n| **CORS bypass** | `browser_fetch` from extension background | N/A | Limited |\n| **Network monitoring** | `browser_wait_for_network` via CDP | Built-in | None |\n| **CSP-strict sites** | Chrome Debugger API throughout | Works (headless) | Limited |\n| **Custom dropdowns** | Angular Material, React Select support | Works (headless) | Limited |\n| **Install** | `claude mcp add` + extension from the Chrome Web Store | `npx @playwright/mcp` | Manual clone |\n\n### The pages that defeat everything else\n\nThe reason this works where headless dies is not that it slips past anything. It is that\nthere is nothing to slip past: it is your Chrome, your session, your consent. What is left\nis the hard part — pages that fight *any* automation because of how they are built.\n\nEvery release is gated on a flow test against a real Chrome that has to survive exactly\nthose. Latest run, v1.29.0: **40/40 tools exercised, 51 checks, 0 failures**, including\n\n- **strict CSP** — navigate, read, execute, wait and click all still work (falls back to\n the Chrome Debugger API when script injection is blocked)\n- **cross-origin iframes** — seen into and reached inside\n- **shadow DOM** — selectors reach through it\n- **controlled inputs** — `fill` sticks in a React-style controlled field\n- **honesty checks** — `click` refuses a 0×0 element instead of hitting (0,0), and says so\n when the page never took the event\n\nThat last group matters most. A tool that quietly reports success is worse than one that\nfails, because you build on the answer. Where we still fall short of it, it is written\ndown: see [#19](https://github.com/Agent360dk/browser-mcp/issues/19).\n\n> **Corrected 2026-09-07.** This table used to say Playwright MCP was headless and made you\n> log in every time. That was wrong, and it had been wrong for a while — Microsoft's own README\n> documents a persistent profile as the default, plus a browser extension for using the Chrome\n> you already have. The row that actually survives is the one above it, and it is their\n> documented limitation, not our claim: *\"A persistent profile can only be used by one browser\n> instance at a time, so concurrent MCP clients sharing the same workspace will conflict.\"*\n> If you run one agent, Playwright MCP will serve you well. The difference shows up when you\n> run twenty against the same logged-in browser.\n\n> **On the name:** the similarly-named `browsermcp.io` (`@browsermcp/mcp`) is a different, unaffiliated project with no commits since April 2025. This is Browser MCP by Agent360 (`@agent360/browser-mcp`) — actively maintained. [Full side-by-side →](https://browsermcp.dev/compare/browsermcp-io/)\n\n### Environment variables\n\nBoth are optional. Neither is needed for normal use.\n\n| Variable | Effect |\n|---|---|\n| `BROWSER_MCP_CHECK_NPM=1` | Makes `browser_provide_feedback` also compare this server against the latest version published on npm. Off by default, so the call stays fast and works offline. |\n| `BROWSER_MCP_EXTENSION_ID=<32-char id>` | Pins the server to one specific Chrome extension. Use it when more than one copy of Browser MCP is loaded and you want a given session to always talk to the same one. |\n\n## 40 Tools\n\n### Navigation & Content\n| Tool | Description |\n|------|-------------|\n| `browser_navigate` | Navigate to URL (reuses tab, or `new_tab=true`) |\n| `browser_get_page_content` | Get page text or HTML |\n| `browser_screenshot` | Screenshot via Chrome Debugger (works even when tab isn't focused) |\n| `browser_execute_script` | Run JavaScript in page context |\n| `browser_extract_list` | Read every row of a long/virtualised list by scrolling its container until no new rows appear |\n\n### Interaction\n| Tool | Description |\n|------|-------------|\n| `browser_click` | Click via CSS or text selector (`text=Submit`, `button:text(Next)`) |\n| `browser_fill` | Fill input fields (works on CSP-strict sites) |\n| `browser_press_key` | Keyboard events (Enter, Tab, Escape, modifiers) |\n| `browser_scroll` | Scroll to element or by pixels |\n| `browser_wait` | Wait for element to appear |\n| `browser_hover` | Hover for tooltips/dropdowns |\n| `browser_select_option` | Native `` via Chrome Debugger API (no dialog) |\n| `browser_drop_file` | Upload via drop-zones: finds hidden `` in target subtree/parent (up to 2 levels). Use when `browser_upload_file` fails because the zone has no visible input |\n\n### Diagnostics & feedback\n| Tool | Description |\n|------|-------------|\n| `browser_provide_feedback` | Self-check + report in one call. Compares this server against the latest on npm, the connected extension against this server, and detects **more than one Browser MCP extension connected at once** — the three things that explain most \"it just stopped working\" moments. Returns a verdict (`current` / `outdated` / `conflict` / `disconnected`), concrete fix steps, and a pre-filled issue link for whatever is genuinely missing. Your agent calls it on its own whenever a tool blocks it |\n| `browser_about` | Project info + pre-filled links to submit a wish, use-case, or bug |\n\n## Multi-Session Support\n\nEach Claude Code conversation gets its own MCP server on a unique port (9876-9895). The Chrome extension connects to all active servers simultaneously.\n\n```\nClaude Session 1 ←(stdio)→ MCP :9876 ←(WS)→\nClaude Session 2 ←(stdio)→ MCP :9877 ←(WS)→ Chrome Extension → Browser\nClaude Session 3 ←(stdio)→ MCP :9878 ←(WS)→\n```\n\n- **Session isolation** — each session gets a color-coded Chrome Tab Group\n- **Tab ownership** — sessions can only see and control their own tabs\n- **Auto-cleanup** — processes exit when Claude Code closes the conversation\n- **Ports are taken on demand** — a server binds its port on the first browser call, not\n at startup, and releases it 5 minutes after its last tab closes. A chat that never\n touches the browser never occupies a slot.\n\n### Running the agent on another machine\n\nThe extension only connects to `127.0.0.1`, deliberately — it will not talk to a remote\nWebSocket. If your MCP gateway runs on a different box than your browser, forward the port\nrange over SSH.\n\nRecipe below contributed by [@bkuri](https://github.com/Agent360dk/browser-mcp/issues/1),\nwho ran into exactly this and solved it. Linux + systemd; needs `autossh` locally and your\npublic key already on the server:\n\n```ini\n# ~/.config/systemd/user/browser-mcp-tunnel.service\n[Unit]\nDescription=SSH tunnel for browser-mcp WebSocket (ports 9876-9895)\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nExecStart=/bin/sh -c '/usr/bin/autossh -M 0 -N \\\n -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \\\n -o ExitOnForwardFailure=yes -o LogLevel=ERROR \\\n $(for p in $(seq 9876 9895); do printf \" -L %s:127.0.0.1:%s\" \"$p\" \"$p\"; done) \\\n server-name'\nRestart=on-failure\nRestartSec=5\nEnvironment=\"AUTOSSH_GATETIME=0\"\n\n[Install]\nWantedBy=default.target\n```\n\nReplace `server-name`, then `systemctl --user enable --now browser-mcp-tunnel.service`.\n\n> The original recipe listed ports 9876-9885 by hand — the range was ten back then. It is\n> twenty now, so the loop above generates them instead of hard-coding a list that goes\n> stale the next time the range changes.\n\n## Built-in Provider Integrations\n\n`browser_extract_token` navigates to the provider's API settings page and guides token extraction:\n\n| Provider | Token Format | Dashboard |\n|----------|-------------|-----------|\n| Stripe | `sk_test_...` / `sk_live_...` | stripe.com/apikeys |\n| HubSpot | `pat-...` | app.hubspot.com |\n| Slack | `xoxb-...` | api.slack.com/apps |\n| Shopify | Admin API token | admin.shopify.com |\n| Pipedrive | UUID | app.pipedrive.com |\n| Calendly | JWT | calendly.com |\n| Mailchimp | `...-us1` | admin.mailchimp.com |\n| Google | OAuth Client | console.cloud.google.com |\n| LinkedIn | Client ID/Secret | linkedin.com/developers |\n\n## Architecture\n\n```\nextension/\n manifest.json # Manifest V3\n background.js # Service worker — Chrome API dispatcher, session tab groups\n offscreen.js # Persistent WebSocket bridge (multi-port scanning)\n popup.html/js # Status UI — sessions, tabs, action log\n\nmcp-server/\n index.js # MCP server (stdio) + WebSocket client\n tools.js # 40 tool definitions\n bin/cli.js # Install CLI\n```\n\n### How It Works\n1. Claude Code starts → spawns MCP server via stdio\n2. MCP server binds to first available port (9876-9895)\n3. Extension's offscreen document scans ports every 2s\n4. WebSocket connection established\n5. Commands flow: Claude Code → MCP → Extension → Chrome APIs\n6. Process auto-exits when Claude Code closes (stdin detection)\n\n## Keeping it updated\n\nBrowser MCP has two parts, and they update independently — how the **extension** updates depends on how you installed it:\n\n| Part | Install method | How it updates |\n|------|----------------|----------------|\n| **MCP server** | any | **Automatic.** Runs via `npx @agent360/browser-mcp@latest`, so every Claude Code session pulls the newest from npm. Nothing to do. |\n| **Extension** | **Chrome Web Store** | **Automatic.** Chrome updates it in the background (usually within a few hours). Nothing to do. |\n| **Extension** | **Unpacked** (`npx … install` or manual zip) | **Manual.** Chrome never auto-updates a load-unpacked extension. Re-run `npx @agent360/browser-mcp install`, then open `chrome://extensions` → Browser MCP → **↻ reload**. |\n\n**Not sure which you have?** Open `chrome://extensions` and find Browser MCP. If it shows a **\"Loaded from /path/…\"** line, it's unpacked (manual updates). If there's no such line, it came from the Chrome Web Store (auto-updates).\n\n**Want zero-maintenance updates?** Install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl), then run `claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest` to register the server. After that, both parts stay current on their own — as long as your config uses `@agent360/browser-mcp@latest`.\n\n## Troubleshooting\n\n**\"Chrome extension not connected\"**\n- Check extension is loaded in `chrome://extensions`\n- Click the extension popup → \"Reconnect\"\n- Wait 2-3 seconds for port scan\n\n**Screenshot fails**\n- Uses Chrome Debugger API (works even when tab isn't focused)\n- Falls back to `captureVisibleTab` if debugger unavailable\n\n**Click doesn't work on SPA**\n- Try text selector: `browser_click(\"text=Submit\")`\n- Uses real mouse events via Chrome Debugger API automatically\n\n**Stale processes**\n- Processes auto-exit when Claude Code closes (stdin detection)\n- Idle timeout: 4 hours without commands → auto-exit\n- Manual cleanup: `lsof -i :9876-9895 | grep LISTEN`\n\n## 💡 Help Shape Browser MCP\n\nBrowser MCP is built in the open and shaped by the people using it.\n\n### Browse what others want / built\n- 💡 **[Wishlist →](WISHLIST.md)** — features people are asking for\n- 🎯 **[Use-cases →](USE_CASES.md)** — what others have built (LinkedIn ICP scraping, vendor research, daily ops, …)\n\n### Contribute in 30 seconds\n- 💡 [Wish for a feature](https://github.com/Agent360dk/browser-mcp/issues/new?template=wish.yml)\n- 🎯 [Share a use-case](https://github.com/Agent360dk/browser-mcp/issues/new?template=use-case.yml)\n- 🐛 [Report a bug](https://github.com/Agent360dk/browser-mcp/issues/new?template=bug.yml)\n\nOr just **ask Claude** — it knows about the `browser_about` tool and will draft + submit on your behalf when you say things like *\"I wish browser-mcp could …\"* or *\"share my browser-mcp use-case\"*.\n\n### If it works for you\n\nThe Chrome Web Store ranks on ratings, and we have none — so a sentence from you moves this\nfurther than anything we can write. [Leave a review](https://chromewebstore.google.com/detail/agent360-browser-mcp/jdehgalffmffhfhmmhaokfbfnafnmgcl/reviews)\nif it earned one, and say so honestly if it did not. No signup, no reward, nothing gated\nbehind it — we just have no signal at all right now.\n\n## License\n\nMIT — [Agent360](https://agent360.dk)\n", "bytes": 24259, "sha": "2d635db08784cf3edc94a5dbbd790e6c83535d606193966b83bf7d828ed2a60e", "repo_slug": "agent360dk/browser-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_agent360dk_browser_mcp_bdc12dd5/readme" }