Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@browser-buddy read the private GitHub issue in my active tab"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Let your coding agent read pages through YOUR real, logged-in browser.
Claude Code's WebFetch gets 403'd on most sites. Ask it to pull up a doc, check a Reddit thread, or look at a GitHub issue, and it comes back with a 403 — because server-side fetchers don't have your cookies, your logins, or your sessions.
Browser Buddy is a small local MCP bridge: a Chrome extension (Manifest V3) talks to a Python native-messaging host, which exposes two MCP tools. Your agent reads pages exactly as you see them — logged in, past bot checks — and the page never leaves your machine except into the agent's context.
Stdlib only. No dependencies, no cloud, no API keys.
Tool | What it does |
| Extract readable text (URL, title, cleaned body) from your active Chrome tab |
| Open a URL in a background tab with your real profile (cookies/logins), extract its text, close the tab |
Related MCP server: byob
┌─────────────┐ MCP (JSON-RPC 2.0 ┌──────────────────┐ Unix socket ┌───────────────────┐ Native Messaging ┌────────────────┐
│ Claude Code │ ── over stdio, NDJSON ──▶ │ browser_buddy_mcp │ ── NDJSON ──▶ │ browser_buddy_host │ ── 4-byte LE ──▶ │ Chrome extension │
│ │ ◀────────────────────── │ .py │ ◀──────────── │ .py │ ◀── JSON ─────── │ (your profile) │
└─────────────┘ └──────────────────┘ └───────────────────┘ └────────────────┘
▲ │ │
│ │ one request per socket connection; │ chrome.tabs +
└──────── page text lands here ──────────┘ host routes replies by request id │ chrome.scripting
▼
real logged-in pageExtension (extension/): MV3 service worker. Holds a persistent chrome.runtime.connectNative port to the host (auto-reconnects). Executes read_active_tab / open_and_read_url against your real tabs and posts extracted text back.
Host (host/browser_buddy_host.py): launched by Chrome. Bridges the extension (length-prefixed stdio) and the MCP server (Unix socket at $TMPDIR/browser-buddy/browser-buddy.sock). Correlates requests by id, with a 90 s timeout.
MCP server (mcp_server/browser_buddy_mcp.py): hand-rolled JSON-RPC 2.0 over stdio (no mcp package). Forwards tool calls to the host; returns page text as MCP content.
Open chrome://extensions, enable Developer mode.
Load unpacked → select the extension/ folder.
Copy the extension ID shown under "Browser Buddy".
cd host
./install.sh <paste-extension-id-here>This writes com.browserbuddy.host.json into Chrome's NativeMessagingHosts
directory (Linux/macOS) pointing at browser_buddy_host.py. Restart Chrome,
then open the extension's service worker console — you should see
[browser-buddy] native host connected.
claude mcp add browser-buddy -- python3 /absolute/path/to/mcp_server/browser_buddy_mcp.pyOr in ~/.claude.json / project .mcp.json:
{
"mcpServers": {
"browser-buddy": {
"command": "python3",
"args": ["/absolute/path/to/browser-buddy/mcp_server/browser_buddy_mcp.py"]
}
}
}Requires Python 3.9+. No pip install needed.
Log in to a site WebFetch can't reach in your normal Chrome (e.g. a private GitHub issue, a login-walled doc).
In Claude Code: "Use browser-buddy to read my active tab."
Or: "Use browser-buddy's open_and_read_url to read ." — a background tab opens, the text is extracted, the tab closes itself.
Vendor scrapers (Firecrawl, etc.) fetch pages server-side: they never have your cookies, can't get past SSO/2FA/login walls, can't see what you see behind an account, and they charge per page. The official Claude in Chrome goes the other way — full autonomous browser control — but ships a permission dialog per tool call (dozens per session) and sits at 2.7 stars on the Chrome Web Store.
Browser Buddy picks the middle: read-only access through the browser you already logged into. No credentials leave your machine, nothing to pay per page, no dialog spam — just "let the agent see what I see."
Chrome/Chromium only. The extension is the whole trick; no Chrome, no tool.
Read-only by design. It extracts text; it doesn't click, type, or fill forms. That's a feature for trust, but it means CAPTCHAs / interactive gates still stop it.
Text extraction is heuristic, not a full readability engine. Heavy SPAs usually work (we wait for load + a settle beat), but exotic layouts may extract noise.
Your real profile = real risk surface. The agent sees everything your browser can see. Only install this if you trust the agent session reading your tabs.
MV3 service workers are ephemeral. The extension auto-reconnects its native port, but a cold start can add ~1 s to the first call.
One request at a time per socket connection is fine for an agent; this is not built for concurrent scraping fleets.
Long pages are truncated at 60k characters (flagged with (truncated)).
python3 tests/test_smoke.py # 17 tests: framing, bridge routing, MCP handlers
node --check extension/background.jsMIT — see LICENSE.
Open a URL in a background Chrome tab using the user's real browser profile (cookies and login sessions included), extract its readable text, then close the tab. For pages behind logins, paywalls-with-session, or bot checks that defeat server-side fetchers.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | http(s) URL to open and read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses that a background tab is created, that the user's real cookies/login sessions are used, and that the tab is closed afterward, so the agent knows no tab is left behind. It omits failure behavior, timeouts, and any rate-limit or permission caveats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The what/how sentence comes first and the when-to-use condition follows, which is the right front-loading for a tool selector.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description covers purpose, mechanism, scope conditions, and the return ('readable text'), which is everything an agent needs to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
A single required parameter whose schema description coverage is 100% and which needs no added syntax beyond 'http(s) URL'. The description adds no extra parameter meaning, but by the one-parameter/fully-covered baseline this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (open/read) plus resource (URL), and names the mechanism (background Chrome tab using the real browser profile) and lifecycle (open, extract text, close). This implicitly separates it from read_active_tab, which observes a tab the user already has, without either schema being opened.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear positive-use condition: pages behind logins, session paywalls, or bot checks that defeat server-side fetchers. It does not, however, name read_active_tab or state when to prefer that sibling instead, so routing is left partly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the user's currently active Chrome tab through their real, logged-in browser profile. Returns the page URL, title, and cleaned readable text. Use when WebFetch/fetch is blocked by a 403, login wall, or bot detection.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the important behavioral trait: it reads via the user's real logged-in profile rather than a sandboxed fetch, which explains why it bypasses auth walls. It omits secondary behavior such as whether the tab is focused, what happens with no browser open, or any rate limits, so it stops short of full disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the action, then the return values, then the usage trigger. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description enumerates what is returned (URL, title, cleaned readable text), which is what an agent needs. For a zero-parameter tool this is close to complete; only the failure/no-browser behavior and any tab-focus side effects are left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to clarify and the baseline of 4 applies. No parameter-related ambiguity is introduced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read the user's currently active Chrome tab') plus the mechanism ('through their real, logged-in browser profile') and the return shape (URL, title, cleaned readable text). It is clearly distinguishable from open_and_read_url by the 'currently active tab' scoping, though it never names the sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger condition: 'Use when WebFetch/fetch is blocked by a 403, login wall, or bot detection.' That is strong when-to-use guidance, but it offers no when-not-to-use and does not mention the sibling open_and_read_url as the alternative for non-active-URL fetching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0open_and_read_urlread_active_tabScored across 2 tools
The two tools have overlapping 'read page content' semantics, but their triggers are clearly differentiated: read_active_tab targets the current tab, while open_and_read_url takes a URL and manages its own tab lifecycle. Descriptions make the boundary explicit (active vs. newly opened), so misselection is unlikely.
Both names use snake_case verb-first phrasing (read_active_tab, open_and_read_url). The slight asymmetry ('read_' vs 'open_and_read_') is a minor deviation but still readable and predictable.
Two tools is thin for a browser-based retrieval server, even with a narrow scope. It is not egregious, but typical browser surfaces (list tabs, interact, screenshot) suggest more could reasonably earn a place.
The core use case — reading pages that defeat server-side fetchers — is covered by reading the active tab or an arbitrary URL. However, there is no interaction, tab listing, screenshot, or explicit JS-wait capability, leaving notable gaps for a browser-profile-based tool.
Real Chrome for agents: start a browser, read pages as numbered markdown, click, type, hand off.
A real browser for your agent: render any page, or 25 pages of a site, to clean text.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.
Stealth web automation for AI agents. Login, signup, navigate, screenshot.