0.15.1

Browser MCP

English · 中文

Let your AI really search the whole web. Any site you can reach with a login — Xiaohongshu, Zhihu, X, Douyin, Bilibili, Reddit, or any logged-in site — its content can be captured, and it can be automated in the background: no headless browser, no reverse-engineering, no cookie theft.

Browser MCP is a local MCP server. It lets any MCP-capable AI assistant, inside the session state of your real Chrome:

• Search and capture the content of any site on the web — public pages, JavaScript-rendered pages, and pages that are only visible after login;
• Automate interactions in a background Chrome window — click, scroll, type, press keys, select — without switching you away from the page you're on.

Runs locally; your data stays on your machine: the MCP server and the Chrome extension run on your own machine, over localhost (127.0.0.1) only — there's no extra remote server, and your session is never uploaded.

• Login state never leaks: the extension never requests the cookies permission and never returns or persists cookies — your login state is only used normally by the page inside your own Chrome.
• Records & artifacts stay local: connection, tool-call, and media-download state are kept locally; downloads land on disk with a SHA-256 and aren't reported anywhere else.
• Fully compliant: it doesn't reverse-engineer internal APIs, bypass CAPTCHAs, steal cookies, or bulk-scrape — it behaves exactly like a normal logged-in user browsing.
• The one boundary: the page content you ask the AI to read is returned to your assistant as a tool result (that's its whole purpose). If your assistant is wired to a model API, that content goes to the model service. But login state and cookies never go with it — this boundary is separate from "you hand content to the AI."

What you can do

In one line: if you can reach it with a login, it can be captured. Your AI can search, collect, and operate on any site — Zhihu, Xiaohongshu, X, Douyin, Bilibili, Reddit and beyond — using your logged-in state to get the platform's own data.

• Search directly inside the real platforms: Zhihu, Xiaohongshu, X, Douyin, Bilibili, Reddit — with your logged-in state, getting the platforms' own data, not your agent's built-in search.
• Read any page: article body, visible text, JS-rendered content, data returned by page requests, and content that's only visible after login.
• Drive a page in the background: get a screenshot plus numbered actionable elements in a background Chrome window, then keep clicking, scrolling, typing, pressing keys, selecting options, and uploading files — without leaving the tab you're on.
• Zhihu: search, questions, answers, articles, answer invitations.
• Xiaohongshu: search, an account's posts, note details, full comments (resumable), like/collect, image & video download.
• Douyin: search, video/image-post details, full comments (resumable), like/collect, image & video download.
• Bilibili: video search, content metadata, multi-part info, video or audio-only download.
• X (Twitter): post search, post details.
• Reddit: post search, post details, comments.
• Search: Google, Bing, Sogou.

Current version is 0.15.1. See CHANGELOG.md for release notes.

Final actions that affect external state — like, collect, publish, send, buy, delete — should be confirmed with the user before executing. The extension uses the current Chrome Profile's login state but never returns or persists cookies over MCP.

---

Quick start

1. Requirements

• Python 3.12+
• uv
• Google Chrome

2. Install

Option 1: pip (published, recommended)

pip install ai-browser-mcp

Then run browser-mcp directly (the Chrome extension is bundled in the install; take its directory from the extension_dir returned by browser_status — loading it works the same way). To run a specific version on the fly, use uvx ai-browser-mcp.

Option 2: from source

git clone https://github.com/ywleeo/browser-mcp.git
cd browser-mcp
uv sync

(/path/to/browser-mcp below is the absolute path to this repo in the source setup. With a pip install you don't need a path — just run the browser-mcp command.)

3. Load the Chrome extension

1. Call browser_status and take the extension_dir from the result.
2. Open chrome://extensions.
3. Turn on Developer mode.
4. Click Load unpacked.
5. Pick the directory returned by extension_dir.
6. Call browser_status again.

A successful connection returns:

{
  "state": "connected",
  "connected": true,
  "bridge_port": 17880,
  "server_version": "0.15.1",
  "install_mode": "source",
  "project_root": "/path/to/browser-mcp",
  "source_commit": "<git-commit>",
  "upgrade_check_command": "uv --directory /path/to/browser-mcp run browser-mcp upgrade --check --json",
  "upgrade_apply_command": "uv --directory /path/to/browser-mcp run browser-mcp upgrade --apply --json"
}

bridge_port may also fall in 17880..17889. The extension normally only needs to be loaded once and reconnects automatically when the MCP server starts. After updating the extension, click Reload in chrome://extensions if it doesn't pick up automatically.

4. Connect your AI client

Codex

codex mcp add browser_mcp -- \
  uv --directory /path/to/browser-mcp run browser-mcp

Or write the Codex MCP config directly:

[mcp_servers.browser_mcp]
command = "uv"
args = [
  "--directory",
  "/path/to/browser-mcp",
  "run",
  "browser-mcp",
]

Restart Codex after adding or editing the config. Once connected, use the MCP tools. To remove it: codex mcp remove browser_mcp.

Claude Desktop

Add this to your Claude Desktop config file:

{
  "mcpServers": {
    "browser-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/browser-mcp",
        "run",
        "browser-mcp"
      ]
    }
  }
}

Save and restart Claude Desktop.

DeepSeek Harness (dsh)

Register the server as native dsh MCP tools with one command:

dsh plugin --profile web add "github:ywleeo/browser-mcp#main"

Restart dsh web. The tools appear as mcp__browser__* (for example mcp__browser__browser_read, mcp__browser__browser_snapshot). This is a configuration-only dsh bundle: it wires @deepseek-ai/dsh-mcp-client to the server, and the server itself is fetched from PyPI (ai-browser-mcp) via uvx, so uv must be on PATH but no local checkout is required. Remove it with dsh plugin --profile web remove "@ywleeo/dsh-browser-mcp".

To make dsh run a local checkout instead of the published PyPI release — handy for trying out your own changes — use this instead:

python3 scripts/install-dsh.py --profile web

It writes an insert entry pointing at the current project directory into ~/.dsh/profiles/<profile>/cordis.patch.yml, and is idempotent (it skips when the plugin id is already present). Pass --uv / --project-dir if uv or the project root cannot be located automatically.

5. Start using it

Once connected, just describe what you want in plain language:

“Search Zhihu for answers about MCP.” “Download all images from this Xiaohongshu note to /abs/path.” “Read this Douyin video's content and comments.” “Open this page, fill the search box from the screenshot, and click search.”

More copy-paste examples are in Examples.

---

Reference

Upgrading

Source installs provide a safe upgrade command an agent can run directly. First check the version and repo state:

uv --directory /path/to/browser-mcp run browser-mcp upgrade --check --json

Then apply if it's safe:

uv --directory /path/to/browser-mcp run browser-mcp upgrade --apply --json

The updater only accepts Git branches that have an upstream, and follows these safety rules:

• Refuses to upgrade if the worktree has untracked or uncommitted files.
• Refuses to upgrade if local and remote have diverged; no implicit merge commit is created.
• Only updates source with git pull --ff-only.
• Syncs locked dependencies with uv sync --frozen, never touching uv.lock.

After --apply succeeds and returns restart_required: true, have the client reconnect the MCP server — start a new task or reconnect it in Codex; only restart the client if it can't reconnect on its own. A fresh MCP server refreshes the extension bundle, and the already-loaded Chrome extension auto-reloads by build ID.

Agents don't need to guess the project path: call browser_status and use the returned upgrade_check_command / upgrade_apply_command. If installed from a wheel or another package manager, install_mode is "package", so upgrade with your original installer instead of mutating an arbitrary Git repo.

Extension permissions

• <all_urls>: to open public HTTP(S) pages explicitly requested by the caller, and to support the per-site adapters. It never crawls browsing history on its own.
• debugger: to capture page request responses, to send trusted browser input events in comment streams and visual interaction, and to write local files straight into a page's file input without the OS file picker opening.
• tabs, scripting: to manage isolated background tabs and run the bundled, fixed extraction scripts.
• storage, alarms: for local pairing config and MV3 service-worker keep-alive.

The extension does not request the cookies permission. Login state is only used normally by the target page inside the current Chrome Profile; cookies are never returned through MCP tool results.

Zhihu, Xiaohongshu, Douyin, X and Reddit tools check the platform login state of the current Chrome Profile before doing anything:

• Logged in: proceed.
• Not logged in: stop and return the platform's login URL, and the client prompts the user to log in.
• Can't tell: stop, to avoid touching protected content when the login state is ambiguous.

Login state isn't cached. Once you finish logging in in Chrome, just retry the original request.

Media download

xhs_download and douyin_download accept these common parameters:

• media: choose images, video, or all.
• output_dir: optional absolute dir; defaults to downloads under the Browser MCP data dir.
• overwrite: default false; a same-named file gets a new name unless explicitly set.
• max_file_mb: per-file size cap, default 1024 MiB.

Before downloading, the tool reads the post detail through the current Chrome login state, then validates the page-derived media URL against platform CDN allowlists, public addresses, hop-by-hop redirects, and the response media type. Files stream to a .part temp file and atomically land on disk; the result includes the final path, byte count, Content-Type, and SHA-256.

bilibili_download_video and bilibili_download_audio share the same absolute-dir, overwrite, and size rules. Bilibili usually returns separate DASH video/audio tracks: the video tool losslessly muxes them into MP4 via ffmpeg when available, and returns the two tracks as separate files when it isn't, rather than pretending to have a complete video. The audio-only tool keeps the most compatible track. For multipart videos, pass ?p=N in the URL.

Comment completeness & resumable collection

xhs_comments and douyin_comments scroll the comment stream, expand replies, and watch the page's own signed pagination requests. In the result, complete means every discovered comment stream reached its terminal page; limit_reached means max_comments truncated the collection; pages_fetched and scrolls help diagnose the run.

A popular post's comment stream can take minutes to scroll — longer than any MCP client is willing to wait in one call — so a single call doesn't try to finish: when time_budget_seconds (default 40s) elapses the collection suspends instead of failing, returning the newly gathered comments and a session_id. Call again with the same url plus that session_id to resume from where it stopped, without re-gathering already-collected comments:

• budget_exhausted means the run wrapped up at the budget; the data is complete and usable, just not fully collected yet.
• A non-empty session_id means you can resume; an empty one means it's done (finished, hit the cap, or the stream bottomed out).
• collected_total is the session's cumulative count; compare with total to gauge progress.
• Each call's items holds only the newly collected comments; merge them yourself.

A suspended session keeps a background collection window that closes after 5 minutes idle, after which an old session_id is invalid and you must start over. Raise time_budget_seconds to resume fewer times, but make sure the MCP client's single-call timeout (commonly 60s) leaves room.

Like & collect

xhs_like, xhs_collect, douyin_like, and douyin_collect take a post url and the desired enabled state (default true). The tool reads the current state, clicks once only if it's out of sync, then polls to verify; passing the same state again doesn't toggle it back. Pass enabled=false to unlike or uncollect.

These four tools modify external account state for the current Chrome Profile. The MCP client must get the user's explicit confirmation immediately before each call; the tool won't auto-retry a click that didn't verify.

Extension troubleshooting

• state: disconnected: confirm the extension is enabled, then click Reload on its detail page.
• Port in use: the service auto-tries 17880..17889; trust the bridge_port in the status result. It monitors the real MCP host behind uv and frees the listening port automatically when the host exits, so the agent doesn't have to guess at and kill other processes.
• Pool exhausted by idle sessions: it can't happen. A server whose MCP host is alive but stopped using Browser MCP retires itself once no MCP call has arrived for BROWSER_MCP_IDLE_TIMEOUT_SECONDS (default 3600) and hands its port back. If a starting server still finds every port taken, it reclaims the least recently used one (idle past BROWSER_MCP_RECLAIM_IDLE_SECONDS, default 300), so a new session can always come up. When nothing is reclaimable, the startup error names the PID, host PID, and idle time holding each port instead of just saying the range is busy. Note that the extension connects to every pooled port on its own, so socket presence says nothing about whether a server is still wanted -- only real MCP traffic does.
• A dropped connection no longer discards page state: the brief disconnect an MV3 service worker causes when it sleeps only releases debugger attachments, keeping the tab and window for the reconnect. The window is reclaimed only when the MCP server stops on purpose, or when the same port stays unreachable for five minutes.
• Changed extension dir: rely on the latest extension_dir from browser_status.
• Never share pairing.json or pairing-token; they contain local connection credentials.

A special process supervisor can take the host PID via BROWSER_MCP_OWNER_PID; set it to 0 only to disable host-liveness monitoring. Normal Codex, Claude, or CLI configs don't need this variable.

Both reclamation thresholds are tunable too: BROWSER_MCP_IDLE_TIMEOUT_SECONDS sets how long a server may sit unused before retiring (0 disables self-retirement), and BROWSER_MCP_RECLAIM_IDLE_SECONDS sets how long one must have been idle before a starting server may reclaim its port. Reclamation only targets a process whose PID and start time still match the recorded lease; a PID the kernel has reused loses the stale record and is never signalled.

MCP tools

These tools are called automatically by any MCP-capable client. In daily use just describe your goal; you don't need to fill in parameters by hand.

Examples

Just ask an MCP-capable client in plain language:

• “Read this page and summarize the key points.”
• “Open this page, fill the search box from the screenshot, and click search.”
• “Scroll down and click the contact-us button.”
• “Download all images from this Xiaohongshu note to /abs/path.”
• “Download this Douyin video and return the path and SHA-256.”
• “Check whether I'm logged into Xiaohongshu.”
• “Search Zhihu for answers about MCP.”
• “Read today's Zhihu answer invitations.”
• “Search Xiaohongshu for recent camping notes.”
• “Read this Xiaohongshu note's body and images.”
• “Get all comments and replies on this Xiaohongshu note.”
• “Like and collect this Xiaohongshu note.” (the client confirms before calling)
• “List every post my Xiaohongshu account has published.”
• “Search Douyin for posts about '牵手 APP'.”
• “Read this Douyin video's content and comments.”
• “Unlike this Douyin post.” (the client confirms before calling)
• “Search Bilibili for videos about OpenAI, and read the first video's meta.”
• “Download this Bilibili video, and also extract an audio-only track.”
• “Search X for the latest posts about OpenAI.”
• “Read this X post's body and engagement data.”
• “Search Reddit for high-scoring posts about MCP.”
• “Read this Reddit post and the first 20 comments.”
• “Search for Browser MCP on Google, Bing, and Sogou.”

Each page change produces a fresh set of element numbers; the agent should use the numbers from the latest screenshot.

Running directly

To start the stdio server manually:

uv run browser-mcp

The process waits for MCP JSON-RPC on stdin; no output in the terminal is normal.

License

MIT