# tiny-browse > Web search and page reading for local AI agents and Node.js, built for agents that run on your own machine. It searches Google in the user's installed Chrome (DuckDuckGo and Bing as fallbacks), reads the best results and returns clean Markdown within a hard token budget. One zero-dependency npm package (@shubhamcodess/tiny-browse, 126 kB) that is both an MCP server and a library. No API keys, no bundled browser, no LLM inside. MIT licence. Install: `npm install -g @shubhamcodess/tiny-browse` (Node.js 22+), then `tiny-browse doctor`. Agents run it with `npx -y @shubhamcodess/tiny-browse mcp`. As a library: `npm install @shubhamcodess/tiny-browse`. MCP tools: `web_search` (query, max_results, read, max_tokens, site, freshness, return_images) and `web_fetch` (urls, max_tokens, focus, cursor, render, return_images). Library: `webSearch(input, options?)`, `webFetch(input, options?)`, `createClient(options?)`, `doctor(options?)`. Errors are `TinyBrowseError` with `code`: chrome_not_found, timeout, blocked, network, private_address, aborted, invalid_input. ## Docs - [Full documentation as one file](https://shubhamcodess.github.io/tiny-browse/llms-full.txt): README plus every guide, plain Markdown - [Docs page](https://shubhamcodess.github.io/tiny-browse/docs/): install, agents, library API, errors, MCP tools, configuration - [Library API](https://github.com/shubhamcodess/tiny-browse/blob/main/docs/LIBRARY.md) - [Errors and how to handle them](https://github.com/shubhamcodess/tiny-browse/blob/main/docs/ERRORS.md) - [MCP tools and HTTP server](https://github.com/shubhamcodess/tiny-browse/blob/main/docs/TOOLS.md) - [Configuration](https://github.com/shubhamcodess/tiny-browse/blob/main/docs/CONFIGURATION.md) ## FAQ - **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 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. ## Project - [Source code](https://github.com/shubhamcodess/tiny-browse) - [npm package](https://www.npmjs.com/package/@shubhamcodess/tiny-browse) - [Changelog](https://github.com/shubhamcodess/tiny-browse/blob/main/CHANGELOG.md) - [Security](https://github.com/shubhamcodess/tiny-browse/blob/main/SECURITY.md) - [whatcmd](https://github.com/shubhamcodess/whatcmd): a CLI that uses tiny-browse as a library for web lookups