Documentation

Install it, connect your local agent, call it from Node.js, handle every error. Rendered from the guides in the repository, so it matches the package on npm.

$ npm install @shubhamcodess/tiny-browse

Getting started

tiny-browse is one npm package, @shubhamcodess/tiny-browse, with two faces: an MCP server that gives your local agent web_search and web_fetch, and a Node.js library with the same engine. Version 0.1.0.

Install

Requires Node.js 22+ and Chrome, Chromium, Edge or Brave (or use the no-Chrome mode).

From npm

npm install -g @shubhamcodess/tiny-browse
tiny-browse doctor

Agents can also run it without installing: npx -y @shubhamcodess/tiny-browse mcp.

From the latest GitHub release

npm install -g https://github.com/shubhamcodess/tiny-browse/releases/latest/download/tiny-browse.tgz

From source

git clone https://github.com/shubhamcodess/tiny-browse.git
cd tiny-browse
npm ci && npm run build
npm link            # or run: node dist/cli.js

Connect to an agent

Claude Code

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

VS Code (GitHub Copilot): .vscode/mcp.json

{
  "servers": {
    "tiny-browse": { "type": "stdio", "command": "npx", "args": ["-y", "@shubhamcodess/tiny-browse", "mcp"] }
  }
}

Cursor, Claude Desktop and most other clients

{
  "mcpServers": {
    "tiny-browse": { "command": "npx", "args": ["-y", "@shubhamcodess/tiny-browse", "mcp"] }
  }
}

tiny-browse config <client> prints the setup for claude-code, claude-desktop, cursor, vscode, codex or generic. To share one warm Chrome between several agents, run tiny-browse serve --http 7777 and connect to http://127.0.0.1:7777/mcp.

The agent gets two tools: web_search (search and read the top results) and web_fetch (read URLs, optionally narrowed with focus or continued with cursor). Parameters: TOOLS.md.

Use as a dependency

npm install @shubhamcodess/tiny-browse
import { webSearch, webFetch } from "@shubhamcodess/tiny-browse";

const { results, pages, markdown } = await webSearch({ query: "node.js stream backpressure", read: 2 });
for (const r of results) console.log(r.rank, r.title, r.url);

const docs = await webFetch({ urls: ["https://go.dev/doc/effective_go"], focus: "goroutines", max_tokens: 2000 });
console.log(docs.pages[0].markdown);

Each call starts what it needs and shuts it down before returning, so short-lived CLIs exit straight away. Use createClient() to reuse one Chrome across calls, mode: "http" to skip Chrome entirely, and TinyBrowseError.code to handle failures. Full API: LIBRARY.md. Handling each error: ERRORS.md.

How it works

  1. Search. Google's results page is loaded in your Chrome and read three independent ways (layout, accessibility tree, selectors), merged by vote, so a page redesign rarely breaks it. If Google is blocked or over its rate budget, DuckDuckGo and Bing are tried.
  2. Read. Each page is fetched over plain HTTP and rendered with scripts off, which is fast; pages that need JavaScript get a full Chrome load. The faster way is remembered per site.
  3. Extract. The main content is found by how the page is laid out, not by class names. Menus, ads, cookie banners and hidden text are dropped.
  4. Fit. The page is split into sections by heading and packed into max_tokens, keeping the sections most relevant to the query.

Limitations

  • Search engines may block automated browsers, depending on your network. Running tiny-browse login once usually helps with Google. Reading pages is not affected.
  • Sites that refuse automated access with a bot check are reported as blocked, never bypassed.
  • No PDF support yet.
  • Tested on macOS and Linux. Windows is untested.

Troubleshooting

Problem Fix
chrome_not_found Install Chrome, or set --browser-path / TINY_BROWSE_CHROME
Google keeps showing CAPTCHAs Run tiny-browse login. Searches use the other engines meanwhile; tiny-browse doctor shows pauses and budgets
Chrome won't start on Ubuntu 24.04 sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
port … is already in use Another tiny-browse serve is running: stop it or choose another port
A page comes back thin Use render: "browser"; the site may need JavaScript or block automation

Library API

npm install @shubhamcodess/tiny-browse

ESM only, Node.js 22 or later, TypeScript types included. The functions, types and error codes below are the public API; see Versioning.

import { webSearch, webFetch, createClient, doctor, TinyBrowseError } from "@shubhamcodess/tiny-browse";

Functions

webSearch(input, options?)

Searches and reads the top results. One-shot: everything it started is shut down before it returns.

const r = await webSearch({ query: "node.js stream backpressure", read: 2, max_tokens: 4000 });
r.results; // [{ rank, title, url, snippet }]
r.pages;   // the pages read: [{ url, finalUrl, title, markdown, tokens, truncated, cursor? }]
r.markdown; // everything as one Markdown document, within max_tokens

Returns SearchResult:

Field Description
query The query
provider google, duckduckgo or bing: the engine that answered
cached True if no engine was contacted
warning Set when results may not match the query (a degraded engine)
results The result list. Empty when nothing was found; this is not an error
pages Pages read from the top results
failed Results picked for reading that could not be read: [{ url, code, message }]
attempts Each engine tried and what happened: [{ provider, status, note? }]
markdown Everything above as Markdown
images With return_images: [{ id, mimeType, data }] (base64)

Input is the web_search tool's parameters: see TOOLS.md.

webFetch(input, options?)

Reads pages. Returns FetchResult: { pages, failed, markdown, images }. Throws if no page could be read; partial failures are listed in failed.

const { pages } = await webFetch({ urls: ["https://go.dev/doc/effective_go"], focus: "goroutines" });
const next = pages[0].cursor ? await webFetch({ cursor: pages[0].cursor }) : undefined;

Input is the web_fetch tool's parameters: see TOOLS.md.

createClient(options?)

A client reuses one Chrome across calls. Always close it.

const client = await createClient({ timeoutMs: 15_000 });
try {
  const a = await client.webSearch({ query: "..." });
  const b = await client.webFetch({ urls: ["https://..."] }, { signal: AbortSignal.timeout(5000) });
} finally {
  await client.close();
}

client.webSearch(input, { signal?, timeoutMs? }), client.webFetch(input, { signal?, timeoutMs? }), client.close(). Calls after close() throw invalid_input.

doctor(options?)

Checks Node, the browser, a test Chrome start and the search budgets. Returns [{ name, ok, detail }]. Pass { startChrome: false } to skip starting Chrome.

Options

All optional, for the functions above and createClient.

Option Description
signal AbortSignal that cancels calls
timeoutMs Time limit per call (default 20000)
mode "chrome" (default) or "http": no Chrome at all. Faster start; Google is skipped and pages that need JavaScript come back thin
useServer "auto": send calls to a running tiny-browse serve --http (found through the cache folder) and use its warm Chrome; otherwise run in-process. Default "never"
config Settings object, as in CONFIGURATION.md. When given, no config files or TINY_BROWSE_* variables are read
cacheDir Folder for caches, rate budgets and the Chrome profile
chromePath Browser executable
cdpUrl Use an already running Chrome (ws://… or http://host:port)
logger Object with any of error, warn, info, debug(message, extra?). Default: silent
logLevel Lowest level passed to logger (default info)

Errors

Every error is a TinyBrowseError with a code:

Code Meaning
chrome_not_found No usable browser, or it would not start
timeout The call exceeded timeoutMs
blocked A CAPTCHA, bot check or rate budget stopped the request
network DNS, connection or HTTP failure
private_address The URL points at this computer or a private network
aborted The signal fired
invalid_input Invalid input or options; the message says what to fix
try {
  await webSearch({ query: "..." });
} catch (err) {
  if (err instanceof TinyBrowseError && err.code === "blocked") {
    // every engine refused: try again later
  } else throw err;
}

What each code means, which ones are safe to retry, and handlers for each: ERRORS.md.

Lifecycle

  • Importing has no side effects: no files, no Chrome, no output.
  • Nothing starts until the first call. The Chrome profile is created then.
  • After a one-shot call or close() nothing is left running, so a short-lived CLI exits immediately.
  • Chrome is stopped if your process exits, or is interrupted (SIGINT, SIGTERM, SIGHUP) without handling the signal itself.
  • The library never writes to stdout or stderr.

Versioning

The package follows semantic versioning. Before 1.0, breaking changes bump the minor version (0.1 → 0.2); new error codes and optional result fields may be added in any release. Changes are listed in the changelog.

Errors and how to handle them

Every error the library throws is a TinyBrowseError with a stable code. Switch on code, not on the message: codes are only ever added, never renamed, while messages may change in any release.

import { webSearch, TinyBrowseError, type TinyBrowseErrorCode } from "@shubhamcodess/tiny-browse";

Not errors

Three outcomes look like failures but are normal results. Check for them before reaching for catch:

  • No results. webSearch returns results: [] when nothing was found. That is an answer, not an exception.
  • Some pages failed. webSearch and webFetch list pages that could not be read in failed: [{ url, code, message }], using the same codes as below. The pages that worked are in pages. webFetch throws only when no page at all could be read, with the first failure's code.
  • Degraded results. warning is set when an engine may be serving results that don't match the query. attempts shows each engine tried and what happened.
const r = await webSearch({ query: "node.js stream backpressure", read: 3 });
if (!r.results.length) return "nothing found";
if (r.warning) log.warn(r.warning);
for (const f of r.failed) log.info(`skipped ${f.url}: ${f.code}`);

The codes

Code When it happens What to do
chrome_not_found No Chrome, Chromium, Edge or Brave was found, or it would not start Install one, pass chromePath, or retry with mode: "http"
timeout The call took longer than timeoutMs (default 20 s) Retry once, with a larger timeoutMs or a smaller read
blocked A CAPTCHA, bot check, consent page or rate budget stopped the request Do not retry in a loop. Try again later; tiny-browse login helps with Google
network DNS, connection or HTTP failure Retry once after a short wait
private_address The URL points at this computer or a private network Don't retry. Allow the host with fetch.allowHosts if it is intended
aborted Your signal fired Nothing: you cancelled it
invalid_input Bad input or options, or a call on a closed client. The message says what to fix Fix the call. Retrying will fail the same way

A handler for every code

async function search(query: string) {
  try {
    return await webSearch({ query, read: 2, max_tokens: 4000 });
  } catch (err) {
    if (!(err instanceof TinyBrowseError)) throw err;
    switch (err.code) {
      case "chrome_not_found":
        // no browser: plain HTTP still works (Google is skipped)
        return webSearch({ query, read: 2 }, { mode: "http" });
      case "timeout":
      case "network":
        // transient: one retry after a pause
        await new Promise((r) => setTimeout(r, 2000));
        return webSearch({ query, read: 2 }, { timeoutMs: 40_000 });
      case "blocked":
        // every engine refused or is over budget: tell the user, don't hammer
        return null;
      case "aborted":
        return null;
      case "private_address":
      case "invalid_input":
      default:
        throw err;
    }
  }
}

Never retry blocked in a loop

blocked means an engine asked for a CAPTCHA or its request budget is used up. tiny-browse already moved on to the next engine before throwing, so a blocked error means every engine refused. Retrying straight away only extends the pause: after each CAPTCHA an engine is paused for 15 minutes, then 1 hour, 4 hours and 24 hours.

A pattern that works, used by whatcmd: after a blocked error, stop searching in your own code for 15 minutes, and keep reading known URLs with webFetch, which is not rate-limited the same way.

let pausedUntil = 0;

async function lookUp(query: string) {
  if (Date.now() < pausedUntil) return null;
  try {
    return await webSearch({ query, read: 2 });
  } catch (err) {
    if (err instanceof TinyBrowseError && err.code === "blocked") {
      pausedUntil = Date.now() + 15 * 60_000;
      return null;
    }
    throw err;
  }
}

tiny-browse doctor (or doctor() in code) shows each engine's budget and any pause.

Timeouts and cancelling

timeoutMs limits one call as a whole (default 20000 ms). Pass a signal to cancel from outside; the call rejects with aborted. Both can be set per call, and on createClient() for every call:

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

try {
  await webFetch({ urls: ["https://example.com/slow"] }, { signal: controller.signal });
} catch (err) {
  if (err instanceof TinyBrowseError && err.code === "aborted") console.log("cancelled");
}

Clients

A client created with createClient() must be closed. Calls after close() throw invalid_input. Use try / finally:

const client = await createClient();
try {
  await client.webSearch({ query: "..." });
} finally {
  await client.close();
}

If your process exits or is interrupted (SIGINT, SIGTERM, SIGHUP) without handling the signal itself, Chrome is stopped for you.

Thin pages

A page that comes back short is not an error. The site may need JavaScript, or block automated browsers. Read it again with render: "browser" to force a full Chrome load:

const r = await webFetch({ urls: [url] });
if (r.pages[0].tokens < 100) await webFetch({ urls: [url], render: "browser" });

Sites that refuse automated access with a bot check are reported as blocked, never bypassed.

Errors over MCP and HTTP

  • MCP. A failed tool call returns a normal tool result with isError: true and the message as text, so the agent sees what went wrong and can choose another query or URL.
  • JSON API (tiny-browse serve --http). POST /search and POST /fetch answer errors as { error, code } with the codes above: status 400 for a body that fails validation, 422 for expected failures (bad input, every engine refused), 500 otherwise. 401 means a missing or wrong bearer token, 403 a cross-origin request.
  • Library with useServer: "auto". Calls sent to a running server rethrow the server's error as the same TinyBrowseError, so your handler works either way.

Logging

The library never writes to stdout or stderr. To see what happened, pass a logger (any object with error, warn, info or debug) and a logLevel:

await webSearch({ query: "..." }, { logger: console, logLevel: "debug" });

MCP tools and server

tiny-browse exposes two MCP tools, over stdio (tiny-browse mcp) or HTTP (tiny-browse serve --http).

Searches the web and reads the best results. Google comes first; DuckDuckGo and Bing are fallbacks.

Parameter Type Default Description
query string required Plain words. Google operators such as site: and "quotes" work
max_results integer 1–10 5 Results to consider
read integer 0–10 3 Top results to open and read; 0 returns only the result list
max_tokens integer 200–200000 6000 Hard limit on the whole answer
site string Only results from this domain
freshness any day week month year any Only recent results
return_images boolean false Also return the main images of the pages read

Returns Markdown with each page read under its result heading, followed by the other results (title, URL, snippet). Pages are chosen one per site, preferring results that match the query well. Long pages keep the sections most relevant to the query. A URL given as query is read directly.

web_fetch

Reads pages by URL.

Parameter Type Default Description
urls string[] (1–10) Absolute http(s) URLs
max_tokens integer 200–200000 8000 Hard limit on the whole answer, shared between the URLs
focus string Return only the sections most relevant to this question
cursor string Continue a page that was cut short
render auto http browser auto auto uses plain HTTP when that works and Chrome when the page needs JavaScript
return_images boolean false Also return the pages' main images

Give urls or cursor. When a page is cut to fit max_tokens, the output ends with a note and a cursor to read the rest.

Output

  • Markdown keeps headings, code blocks with their language, tables, lists, quotes and links (as references by default).
  • Each page is wrapped in <!-- begin untrusted content from <host> --> … <!-- end untrusted content -->, so agents can tell web content from instructions.
  • With MCP protocol 2025-06-18 or later, results also carry structuredContent with the result list, pages, token counts, cursors and timings.
  • With return_images, images are returned as MCP image blocks (PNG, JPEG, GIF or WebP, at most 4 of up to 1 MB by default).

Connecting clients

tiny-browse config <client> prints the setup for claude-code, claude-desktop, cursor, vscode, codex or generic. The command for any stdio client is:

npx -y @shubhamcodess/tiny-browse mcp

HTTP server

tiny-browse serve --http 7777 [--host 127.0.0.1] [--token SECRET]
Endpoint Description
POST /mcp MCP over Streamable HTTP (JSON responses). Sessions are optional
POST /search JSON API: web_search arguments in, { markdown, data, images } out
POST /fetch JSON API: web_fetch arguments in, { markdown, data, images } out
GET /health { ok, name, version }

Errors from the JSON API are { error, code } with the codes listed in LIBRARY.md.

The server:

  • listens on 127.0.0.1 by default and refuses other addresses unless a token is set (--token or TINY_BROWSE_TOKEN; clients send Authorization: Bearer <token>);
  • rejects requests from web pages (Origin check), which also blocks DNS-rebinding attacks;
  • keeps one Chrome warm for every client, and writes a port file to the cache folder so library clients with useServer: "auto" can use it.

Example client configuration (VS Code):

{ "servers": { "tiny-browse": { "type": "http", "url": "http://127.0.0.1:7777/mcp" } } }

Configuration

tiny-browse works without configuration. Settings are read in this order, later ones winning:

  1. Built-in defaults
  2. ~/.config/tiny-browse/config.json (or $XDG_CONFIG_HOME/tiny-browse/config.json)
  3. ./tiny-browse.config.json in the current folder
  4. A file given with --config <file> or TINY_BROWSE_CONFIG
  5. Environment variables
  6. Command-line flags

As a library, pass settings as the config option instead. Then no files or TINY_BROWSE_* variables are read. See LIBRARY.md.

Example

{
  "search": { "providers": ["google", "duckduckgo", "bing"], "read": 3 },
  "output": { "maxTokens": 6000 },
  "fetch": { "allowHosts": ["intranet.example"] },
  "ranking": { "prefer": ["docs.python.org"], "block": ["pinterest.com"] }
}

Unknown keys are rejected with an error that names them.

Settings

Browser

Setting Default Description
browser.path auto-detect Browser executable (Chrome, Chromium, Edge or Brave)
browser.mode launch launch a browser, attach to one at browser.cdpUrl, or off for no browser at all
browser.cdpUrl Remote debugging address of a running Chrome (ws://… or http://host:port)
browser.headless true Run without a window
browser.eager true Start Chrome as soon as the MCP server starts (the library always starts it on first use)
browser.idleTimeoutMs 300000 Stop Chrome after this long unused
browser.onChallenge fallback On a CAPTCHA: fallback to the next engine, or show a window so you can solve it
browser.profileDir cache folder The tiny-browse Chrome profile (never your everyday profile)
Setting Default Description
search.providers ["google", "duckduckgo", "bing"] Engines, in order. Later ones are fallbacks
search.maxResults 5 Default max_results
search.read 3 Default number of results to read
search.limits see below Per-engine request budgets, e.g. { "google": { "perHour": 10 } }

Default request budgets, shared by every tiny-browse process on the computer:

Engine Gap between requests Per minute Per hour Per day
google 8 s + up to 3 s jitter 3 20 100
google-redirect (following result links) 0.25 s + jitter 10 60 200
duckduckgo, bing 3 s + up to 1.5 s jitter 6 60 300

Each limit can be overridden: minGapMs, jitterMs, perMinute, perHour, perDay. When a budget is used up, that engine is skipped and the next one is tried. After a CAPTCHA, an engine is paused for 15 minutes, then 1 hour, 4 hours and 24 hours if it happens again.

Reading pages

Setting Default Description
fetch.timeoutMs 8000 Time limit per page
fetch.maxBytes 5242880 (5 MB) Largest page read
fetch.concurrency 4 Pages read at the same time
fetch.allowPrivateNetwork false Allow local and private network addresses
fetch.allowHosts [] Specific private hosts to allow anyway, as host or host:port

Output

Setting Default Description
output.maxTokens 6000 Default max_tokens for web_search (web_fetch defaults to 8000)
output.links reference Links as reference ([text][1] with URLs listed at the end), inline or text
images.max 4 Most images returned with return_images
images.maxBytes 1048576 (1 MB) Largest image returned

Ranking

Setting Default Description
ranking.prefer [] Domains to favour when choosing which results to read
ranking.block [] Domains never returned or read

Cache and logs

Setting Default Description
cache.enabled true Cache on disk: pages for cache.pageTtlMs, search results for cache.serpTtlMs
cache.dir OS cache folder Caches, rate budgets, the Chrome profile and the server port file
cache.pageTtlMs 3600000 (1 hour)
cache.serpTtlMs 600000 (10 minutes)
callTimeoutMs 20000 Time limit for one tool call
logLevel info silent, error, warn, info or debug. The CLI logs to stderr

The cache folder is ~/Library/Caches/tiny-browse on macOS, $XDG_CACHE_HOME/tiny-browse or ~/.cache/tiny-browse on Linux, and %LOCALAPPDATA%\tiny-browse\Cache on Windows.

Environment variables

Variable Sets
TINY_BROWSE_CHROME browser.path
TINY_BROWSE_CDP_URL browser.cdpUrl and browser.mode: "attach"
TINY_BROWSE_HEADLESS browser.headless (true / false)
TINY_BROWSE_PROVIDERS search.providers, comma-separated
TINY_BROWSE_LOG_LEVEL logLevel
TINY_BROWSE_CONFIG An extra config file
TINY_BROWSE_TOKEN Bearer token for tiny-browse serve --http

Command-line flags

Flag Sets
--config <file> An extra config file
--browser-path <path> browser.path
--cdp-url <url> browser.cdpUrl and attach mode
--headful browser.headless: false
--no-eager browser.eager: false
--no-chrome browser.mode: "off"
--providers <list> search.providers
--max-tokens <n> output.maxTokens
--log-level <level> logLevel