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 doctorAgents 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.tgzFrom 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.jsConnect to an agent
Claude Code
claude mcp add tiny-browse -- npx -y @shubhamcodess/tiny-browse mcpVS 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-browseimport { 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
- 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.
- 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.
- 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.
- 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 loginonce 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-browseESM 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_tokensReturns 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.
webSearchreturnsresults: []when nothing was found. That is an answer, not an exception. - Some pages failed.
webSearchandwebFetchlist pages that could not be read infailed:[{ url, code, message }], using the same codes as below. The pages that worked are inpages.webFetchthrows only when no page at all could be read, with the first failure's code. - Degraded results.
warningis set when an engine may be serving results that don't match the query.attemptsshows 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: trueand 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 /searchandPOST /fetchanswer errors as{ error, code }with the codes above: status400for a body that fails validation,422for expected failures (bad input, every engine refused),500otherwise.401means a missing or wrong bearer token,403a cross-origin request. - Library with
useServer: "auto". Calls sent to a running server rethrow the server's error as the sameTinyBrowseError, 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).
web_search
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
structuredContentwith 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 mcpHTTP 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.1by default and refuses other addresses unless a token is set (--tokenorTINY_BROWSE_TOKEN; clients sendAuthorization: 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:
- Built-in defaults
~/.config/tiny-browse/config.json(or$XDG_CONFIG_HOME/tiny-browse/config.json)./tiny-browse.config.jsonin the current folder- A file given with
--config <file>orTINY_BROWSE_CONFIG - Environment variables
- 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) |
Search
| 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 |