MarcellM01/TinySearch

Spend tokens on answers, not webpages.
TinySearch searches, crawls, and reranks the web locally, then gives your
agent only the evidence worth putting in its context.
Documentation
·
Quick start
·
Python
·
Discord
TinySearch is a self-hosted web-research tool for AI agents. It searches the
web, reads the best pages, removes low-value content, and returns compact
evidence with source URLs.
Your model receives the useful passages instead of paying to process entire
webpages.
TinySearch is part of TinySuite, a suite of focused
tools designed to make agentic operations cheaper by minimizing token usage
through smart retrieval, selection, and context-management techniques.
Choose a tier
| Tier | Use it when | Entry point | Search backend |
| --- | --- | --- | --- |
| 1. Python library | You are building with TinySuite or Python | pip install tinysuite-search | DDGS |
| 2. One-command MCP | An MCP client should launch TinySearch for you | uvx --from "tinysuite-search[server]" tinysearch | DDGS |
| 3. Docker + SearXNG | You want the full self-hosted stack and HTTP MCP | docker compose ... up -d | Bundled SearXNG |
Tiers 1 and 2 need no search service. Tier 3 adds a dedicated SearXNG service,
persistent model storage, and a network MCP endpoint. See the
installation guide for the Docker
setup.
The expensive part of agent research is context
A search result is not yet useful evidence. Agents often have to open several
pages, ingest navigation and boilerplate, and spend paid input tokens deciding
which passages matter.
TinySearch moves that work in front of the model:
That lowers cost in three ways:
- **Smaller model context.** Only the best-ranked evidence chunks are returned,
within a controlled evidence budget.
- **No metered search API required by default.** TinySearch can search through
DDGS without a paid search provider.
- **Local retrieval by default.** ONNX embeddings and hybrid reranking run on
your machine instead of creating embedding API charges.
Search broadly. Read locally. Pay the model only for the evidence that matters.
This is retrieval, not summarization: TinySearch selects the passages worth
keeping with local BM25 and embedding rerank, it doesn't run a model over the
page to rewrite or condense it. Every returned chunk is the original page
text, unedited, so what you cite is what the page actually said. That keeps
the pipeline fast and free to run locally, at the cost of not compacting as
aggressively as a dedicated reduction model could. A learned reduction step
is a direction we may explore later; it isn't part of TinySearch today.
Actual savings depend on the pages, evidence limits, client model, and provider
pricing. TinySearch reduces the web content sent to the model; it does not
control what the client does with that evidence afterward.
The cost panel uses an illustrative $3.00 per million input-token rate and
excludes search, crawling, model output, and downstream agent use.
The naive baseline isn't a strawman product, it's the same pages TinySearch
crawled for each query, fed to the model unfiltered, the way a generic
"search, then fetch the page" tool (a plain web-search-plus-fetch loop, the
kind built into most coding agents) would. Measured against the current
recommended flow (search then scrape_urls) and counted on the actual MCP
tool-result text, TinySearch's primary interface. Reproduce or rerun it
yourself:
Quick start
With uv installed, add TinySearch to any MCP
client:
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; focused scraping also initializes the configured
embedding model. Pre-warm both ahead of time if you will use those workflows:
The MCP and FastAPI servers keep the scraper browser warm between nearby
requests, then close it after browser_idle_shutdown_seconds. Direct Python
calls retain their short-lived, caller-owned lifecycle.
Prefer Docker, a remote MCP endpoint, or a source checkout? Follow the
installation guide.
The MCP tools
| Tool | Use it when |
| --- | --- |
| search(items) | You need fast, backend-ordered discovery without crawling or reranking; batch independent subquestions when useful |