Tinysearch

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

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:

flowchart LR

A[Question] --> B[Search and crawl] B --> C[Local hybrid reranking] C --> D[Compact evidence with source URLs] D --> E[Your agent]

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:

python scripts/benchmark_token_savings.py --json-out report.json

Quick start

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; 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

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.

The interactive browser_* tools give every MCP client connection its own browser and page, so clients sharing one server never see each other's tabs or cookies. At most browser_max_sessions (default 4) are open at once; a new caller waits up to browser_session_wait_seconds (default 30) for one to close, explicitly or after its idle timeout, then gets an error. The FastAPI /browser/* endpoints share one browser, as before.

Prefer Docker, a remote MCP endpoint, or a source checkout? Follow the installation guide.

The MCP tools

TinySearch deliberately stays focused. It is a retrieval layer, not another agent, chat interface, hosted search product, or permanent web index.

See the complete MCP tool reference for parameters and response contracts.

What your agent gets

TinySearch does not spend another model call writing the final answer. The recommended flow is search for lightweight discovery, then scrape_urls for the pages worth reading.

Search returns structured JSON. Use one item for a simple lookup; add multiple items only for independent subquestions or source strategies. domains is a hard positive source restriction and accepts a domain plus its subdomains:

{"items":[{"query":"Form 8-K Tesla","domains":["sec.gov"]}]}

Each search item reports its own results and compact backend attempts. A zero result response is distinct from a blocked, unavailable, or invalid backend. scrape_urls returns selected Markdown evidence and separate related-link navigation candidates, each with independent configured token ceilings.

MCP still uses its standard JSON-RPC transport envelope, including protocol-level errors and optional structuredContent. Python and FastAPI keep their structured JSON contracts for applications that need to store, inspect, or transform the evidence.

How it works

1. search returns backend-ordered titles, URLs, previews, upstream dates, and backend outcomes without starting Chromium or an embedding model.
2. scrape_urls reads one to five known pages concurrently. Omit an item's query or use "*" to keep clean Markdown in page order within the configured token budget.
3. Supply a focused item query when TinySearch should chunk and hybrid-rank that page before returning evidence.
4. The browser_* tools step in only when scrape_urls can't reach the content because it needs interaction. See Browser automation.

Python library

TinySearch also works as a regular Python package:

pip install tinysuite-search

Optional OpenTelemetry export

TinySearch emits vendor-neutral traces and metrics only when OpenTelemetry is explicitly configured. Normal library, MCP, and FastAPI behavior is unchanged when telemetry is not installed or not configured.

Install the optional exporter support for a standalone MCP server:

uvx --from "tinysuite-search[server,telemetry]" tinysearch

The official Docker image includes the same optional support. Set standard OTel variables on either deployment; the common endpoint enables traces and metrics:

OTEL_SERVICE_NAME=tinysearch \

OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 \ OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \ tinysearch serve

http/protobuf is the default and grpc is also supported. Use OTEL_TRACES_EXPORTER=none, OTEL_METRICS_EXPORTER=none, or OTEL_SDK_DISABLED=true to disable telemetry. Standard resource, header, timeout, sampler, and signal-specific endpoint settings are passed through to the OpenTelemetry SDK; treat OTEL_EXPORTER_OTLP_HEADERS as a secret.

TinySearch exports operation/stage timing, outcomes, counts, backend state, browser use, token counts, and embedding model metadata. It never exports queries, URLs, domains, prompts, documents, snippets, request headers, credentials, configuration paths, raw errors, exception stacks, MCP arguments, or MCP results. Direct Python-library users configure their own OTel provider; TinySearch only auto-configures its standalone MCP and FastAPI server entry