v0.1.0 · MCP server + npm library · MITRead the docs

Give your local AI agent the web, in 126 kB.

Searches Google in the Chrome you already have, reads the best results and returns clean Markdown inside a hard token budget. An MCP server for your local agent and a zero-dependency Node.js library. No API keys, no cloud.

$ npm install -g @shubhamcodess/tiny-browse

Then run tiny-browse doctor to check your browser.

Use it in code
Replay: a local agent asks how backpressure works in Node.js streams and calls the web_search tool. tiny-browse searches Google in a headless Chrome, reads the results page three ways and votes, opens the top result, drops its navigation, cookie banner, sidebar and footer, and returns 1,343 tokens of Markdown instead of 68,928 tokens of HTML. The local agent answers and cites nodejs.org.
local agent · web_search

replay · token counts measured with tiny-browse on nodejs.org

Works with every MCP client, and with plain Node.js

One tool call from your local agent. Four steps. Only the answer comes back.

Everything runs on your machine, in a Chrome profile of its own, without your cookies.

  1. 01

    Search

    Google loads in your Chrome. The results page is read three independent ways and merged by vote. DuckDuckGo and Bing take over when Google refuses.

  2. 02

    Read

    Each page is fetched over plain HTTP and rendered with scripts off. Pages that need JavaScript get a full Chrome load. The faster way is remembered per site.

  3. 03

    Extract

    The main content is found from how the page is laid out, not from class names. Menus, ads, cookie banners and hidden text are dropped.

  4. 04

    Fit

    The page is split into sections by heading and packed into max_tokens, keeping the sections most relevant to the query. A cursor reads the rest.

Small on disk. Careful on the web. Exact about tokens.

$ npm pack --dry-run

name: @shubhamcodess/tiny-browse

package size: 126.6 kB

total files: 7

"dependencies": {}

no bundled browser · no API keys · no LLM inside

126 kB, zero dependencies

One package, nothing else installed. It drives the Chrome, Edge, Brave or Chromium already on your computer instead of downloading a browser of its own.

$ tiny-browse doctor

[ok] node >= 22

[ok] browser - Google Chrome

also found: Microsoft Edge

[ok] chrome session - 809 ms

Your browser, found for you

Detects your browser, starts it headless in a profile of its own and stops it when you are done.

max_tokens: 1500

1,343 tokens · truncated: true

cursor: "eyJ1cmwiOi…" → read the rest

A hard token budget

max_tokens is a limit, not a hint. focus keeps the relevant sections; cursor continues a long page.

✓ layout✓ accessibility tree✓ selectors

→ merged by vote: 5 results

google → duckduckgo → bing, when an engine refuses or runs out of budget

Survives search page redesigns

Results are parsed three independent ways and merged by vote, so one changed class name rarely breaks search. Fallback engines take over automatically.

google 3/min · 20/h · 100/day

CAPTCHA → pause 15 min, 1 h, 4 h

GET http://192.168.1.1

× private_address: refused

cookies: none · profile: its own

Careful by default

Strict search budgets shared by every process, no private-network access, pages read without your cookies. Bot checks are reported, never bypassed.

<!-- begin untrusted content from nodejs.org -->

# Backpressuring in Streams

> https://nodejs.org/learn/modules/backpressuring-in-streams

There is a general problem that occurs during data handling…

<!-- end untrusted content -->

Web text is labelled as web text

Every page arrives wrapped in markers with its URL, so your local agent can tell content from instructions and cite its source. Structured results ride along for MCP clients that support them.

For local agents that need the web, and code that needs it too

The same engine behind two doors: MCP tools for your local agent, functions for your Node.js code.

Web search for local agents

A local agent on a local model has no web access. Add tiny-browse as an MCP server and it can search and read pages: no API keys, no cloud service.

claude mcp add tiny-browse -- npx -y @shubhamcodess/tiny-browse mcp

Answers grounded in sources

Every page comes back with its URL and only its relevant sections, so an assistant answers from current pages and cites them instead of guessing.

web_search { "query": "…", "read": 3 }

Current docs for local coding agents

Libraries change after a model’s training cutoff. web_fetch with focus pulls just the part of the docs your local agent needs, code blocks intact.

web_fetch { "urls": [docs], "focus": "goroutines" }

Web lookup inside your own tool

Import it like any npm package. Each call starts what it needs and shuts it down, so a CLI exits straight away. whatcmd does exactly this.

import { webFetch } from '@shubhamcodess/tiny-browse'

Featured use case

whatcmd: plain English to shell commands, with the web as backup

whatcmd runs on a local model. Only when its answer fails does it look the command up, through tiny-browse used as a library.

  • Reference pages first. For kubectl, helm, gcloud and seven more, a fixed docs page is read over plain HTTP with mode: "http".
  • One search at most. Otherwise webSearch reads the top 2 results. blocked is never retried.
  • Measured: 22 / 40 cloud-CLI cases correct with web off, 25 / 40 with it on.
real output · from the whatcmd README
how whatcmd calls it
import { webFetch, webSearch } from "@shubhamcodess/tiny-browse";

// 1. A known reference page: plain HTTP, no Chrome, no search budget
const r = await webFetch(
  { urls: ["https://kubernetes.io/docs/reference/kubectl/quick-reference/"], max_tokens: 30000 },
  { mode: "http", timeoutMs: 15_000 },
);

// 2. Otherwise one search, reading the top 2 results, sharing a warm Chrome if one runs
const s = await webSearch(
  { query: "kubectl rollout history command", read: 2, max_tokens: 3000 },
  { timeoutMs: 15_000, useServer: "auto" },
);
// a "blocked" error is never retried: whatcmd pauses its searches for 15 minutes
abridged from whatcmd/src/browse.ts

Set it up in a minute

Install, check your browser, add one line to your local agent.

  1. Install with npm install -g @shubhamcodess/tiny-browse, or skip it: your local agent can run it with npx.
  2. Check with tiny-browse doctor. It finds your browser and starts it once.
  3. Connect your local agent. tiny-browse config <client> prints the exact snippet.
  4. Ask something current. Your local agent gets web_search and web_fetch.
  • Requires Node.js 22+ and Chrome, Chromium, Edge or Brave. No browser? Use --no-chrome.
  • Tested on macOS and Linux. Windows is untested.
Setup guide

$

real output

Also an npm library

Typed, ESM, side-effect free. Four functions and one error type.

webSearch(input, options?)
Search and read the top results
webFetch(input, options?)
Read pages by URL, with focus and cursor
createClient(options?)
Reuse one Chrome across calls
doctor(options?)
Check Node, the browser and search budgets
TinyBrowseError.code
Seven stable codes to switch on
import { webSearch } from "@shubhamcodess/tiny-browse";

const { results, pages, markdown } = await webSearch({
  query: "node.js stream backpressure",
  read: 2,          // open and read the top 2 results
  max_tokens: 4000, // hard limit on the whole answer
});

for (const r of results) console.log(r.rank, r.title, r.url);
npm install @shubhamcodess/tiny-browse

Questions

Something missing? Open an issue.

What is tiny-browse?

A web search and page reading tool for local AI agents and Node.js, built for agents that run on your own machine. It searches Google in the Chrome you already have, reads the best results and returns clean Markdown inside a hard token budget. It ships as one npm package that is both an MCP server (tools web_search and web_fetch) and a library (webSearch, webFetch, createClient).

Do I need an API key or an account?

No. There is no search API and no cloud service involved. tiny-browse drives a browser on your own computer, so nothing is billed and no key is needed.

Which local agents does it work with?

Any MCP client: Claude Code, Claude Desktop, GitHub Copilot in VS Code, Cursor, Windsurf, Codex, Gemini CLI, Cline and local agents you build yourself, on any model: Ollama and other local models included. tiny-browse config <client> prints the setup for claude-code, claude-desktop, cursor, vscode, codex or generic.

Does it download a browser?

No. It uses an installed Chrome, Chromium, Edge or Brave, in a separate profile of its own, never your everyday profile. Without any browser, the no-Chrome mode (--no-chrome, or mode: "http" in the library) reads pages over plain HTTP; Google is skipped and pages that need JavaScript come back thin.

Will Google block it?

It can, depending on your network. tiny-browse keeps strict request budgets (for Google: 3 a minute, 20 an hour, 100 a day, shared by every tiny-browse process on the computer) and pauses an engine after a CAPTCHA, while DuckDuckGo and Bing take over. Running tiny-browse login once usually helps. Reading pages is not affected.

How does max_tokens work?

It is a hard limit on the whole answer, counted with a model-agnostic estimate. Pages are split into sections by heading and packed in order of relevance to the query (or to focus). When a page is cut short, the result includes a cursor that continues it.

Can I use it from my own code, without MCP?

Yes. npm install @shubhamcodess/tiny-browse, then import webSearch and webFetch. Each call starts what it needs and shuts it down before it returns, so a short-lived CLI exits straight away; createClient() keeps one Chrome warm across calls. whatcmd uses it exactly this way.

What errors can it throw?

Every error is a TinyBrowseError with a code: chrome_not_found, timeout, blocked, network, private_address, aborted or invalid_input. An empty result list is not an error, and webFetch only throws when no page at all could be read; partial failures are listed in failed. The docs show how to handle each code.

Is it safe to point my local agent at the open web?

tiny-browse refuses local and private network addresses, including requests made by pages inside Chrome, reads pages without your cookies, and wraps every page in untrusted-content markers so your local agent can tell web text from instructions. The HTTP server binds to 127.0.0.1 and requires a token for anything else.

Does it read PDFs or work on Windows?

Not yet. PDF support is not implemented, and it is tested on macOS and Linux only; Windows is untested.

Built in the open

One maintainer, MIT licence, issues read by a human.

Shubham Prakash

Shubham Prakash

Full Stack Developer · AI

maker of tiny-browse and whatcmd

Built so a local agent can read the web without a cloud API or a 300 MB browser download.

latest release
v0.1.0 · Nov 8, 2026
tested
142 tests · macOS and Linux CI
stack
TypeScript · Node 22+ · MCP · Chrome DevTools Protocol
license
MIT, zero runtime dependencies

Your local agent can read the web now.

One line in its MCP config. No API keys, no browser download.

$ npx -y @shubhamcodess/tiny-browse mcp