TinySearch

Spend tokens on answers, not webpages.

Part of TinySuite. Comes built in to TinyWebUI, and works with any MCP client.

Read the documentation → tinysuite.dev/docs/tinysearch

TinySearch is the web-research layer of TinySuite, a set of small, local-first tools that make agents spend tokens on useful work rather than overhead. It searches the web, reads the best pages, removes low-value content, and returns compact evidence with source URLs, so your model receives the useful passages instead of paying to process entire webpages.

It is retrieval, not summarization: every returned chunk is the original page text, unedited and still attached to its URL, so what you cite is what the page actually said. In a benchmark against a plain search-then-fetch agent reading the same pages, it sent 64% fewer tokens to the model (docs/token-savings.md).

Highlights

• No vendor in the loop. No TinySearch account, no required API key, no per-request billing, no analytics service or hosted scraped-data cache. DDGS search and local ONNX embeddings are the defaults.

• Source-grounded by construction. A claim in your agent's answer traces back to one specific passage instead of stopping at "the vendor's model said this."

• Selection happens before the model. Local BM25 and embedding rerank pick pages and passages within an evidence budget you control.

• Five small MCP tools. search, scrape_urls, browser_navigate, browser_act and get_current_datetime, with batching so one call can cover independent subquestions.

• A real browser when a page needs one. The browser tools reuse the scraper's Chromium, act only on elements the model has seen, and can't execute code.

• Private by default. Nothing about what was searched is recorded unless you turn activity recording on, and OpenTelemetry export never carries queries, URLs or page text.

• Bring your own stack when needed. SearXNG, Brave, OpenAI-compatible embeddings, an external browser over CDP, proxies, and an optional fallback fetcher.

• Works where agents already work. MCP over stdio or Streamable HTTP, Python, FastAPI, or Docker.

Related MCP server: SSMCP

Quick start

Tiers 1 and 2 need no search service. Tier 3 adds a dedicated SearXNG service, persistent model storage, and a network MCP endpoint; the installation guide covers it.

With uv installed, add TinySearch to any MCP client:

{
  "mcpServers": {
    "tinysearch": {
      "command": "uvx",
      "args": ["--python", "3.12", "--from", "tinysuite-search[server]", "tinysearch"]
    }
  }
}

The client launches TinySearch over stdio when it needs it. No repository clone, hosted account, or paid search key is required.

Fast search starts without Chromium or an embedding model. The first scrape initializes Chromium, and focused scraping also initializes the configured embedding model. Pre-warm both ahead of time if you will use those workflows:

uvx --from "tinysuite-search[server]" tinysearch setup

From Python, pip install tinysuite-search and call search and scrape_urls directly (Python library). The recommended flow is the same everywhere: search for lightweight discovery, then scrape_urls for the pages worth reading.

Documentation

The full reference lives at tinysuite.dev/docs/tinysearch:

In this repository: docs/token-savings.md is the benchmark and the script to rerun it, docs/fallback-fetcher.md is the full contract a fallback fetch service implements, and configs/tinysearch_config.json is an annotated example configuration.

Development

git clone https://github.com/TinySuiteHQ/TinySearch
cd TinySearch
python -m venv .venv
source .venv/bin/activate
pip install -e ".[server]"
python -m unittest discover tests

TinySearch supports Python 3.12 and newer. CI tests Python 3.12, 3.13, and 3.14 across Linux, macOS, and Windows.

Questions, ideas, and bug reports are welcome on Discord, in GitHub issues, or by email.

License

TinySearch reads public pages and returns selected excerpts to the calling client. Search, crawling, local embeddings, and reranking can run without sending page content to an embedding provider. If you choose an OpenAI-compatible embedding backend, that provider receives the text sent for vectorization.

TinySearch is available under the MIT License. Downloaded model weights remain subject to their respective model-card licenses. See NOTICE for third-party distribution details.