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 theweb, reads the best pages, removes low-value content, and returns compactevidence with source URLs.

Your model receives the useful passages instead of paying to process entirewebpages.

TinySearch is part of TinySuite, a suite of focusedtools designed to make agentic operations cheaper by minimizing token usagethrough 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 theinstallation guide for the Dockersetup.

The expensive part of agent research is context

A search result is not yet useful evidence. Agents often have to open severalpages, ingest navigation and boilerplate, and spend paid input tokens decidingwhich 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<br/>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 throughDDGS without a paid search provider.
• Local retrieval by default. ONNX embeddings and hybrid reranking run onyour machine instead of creating embedding API charges.

Search broadly. Read locally. Pay the model only for the evidence that matters.

Actual savings depend on the pages, evidence limits, client model, and providerpricing. TinySearch reduces the web content sent to the model; it does notcontrol what the client does with that evidence afterward.

Quick start

With uv installed, add TinySearch to any MCPclient:

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

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

On first launch, TinySearch installs Chromium and downloads the localembedding model before it starts accepting requests — a one-time delay of aminute or two. To avoid that delay on the first real query, pre-warm bothahead of time:

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

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

Three focused tools

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

See the complete MCP tool referencefor parameters and response contracts.

What your agent gets

TinySearch does not spend another model call writing the final answer. It givesyour existing agent ranked, source-grounded evidence to reason over.

An abridged structured result looks like this:

{
  "schema_version": "1",
  "operation": "research",
  "status": "ok",
  "query": "How does asyncio cancellation work?",
  "sources": [
    {
      "title": "Coroutines and Tasks",
      "url": "https://docs.python.org/3/library/asyncio-task.html",
      "chunks": [
        {
          "text": "Tasks can be cancelled...",
          "tokens": 146,
          "rank": 1,
          "scores": {
            "rrf": 0.91,
            "dense": 0.88,
            "bm25": 0.79
          }
        }
      ]
    }
  ],
  "stats": {
    "search_results": 10,
    "sources_crawled": 4,
    "chunks_considered": 86,
    "chunks_selected": 8
  }
}

MCP tools return the same evidence as a grounded prompt by default, ready forthe client model to use. Pass output_format: "json" when you want thestructured result directly.

How it works

1. Search the web with DDGS or your own SearXNG instance.
2. Hybrid-rank the search results to choose which pages are worth reading.
3. Crawl those pages in parallel and extract readable content.
4. Chunk, deduplicate, and hybrid-rank the combined evidence pool.
5. Return the best passages with their titles, URLs, ranks, and scores.

Dense and lexical ranking happen before the evidence reaches your model. Themodel gets a small, relevant research packet rather than a pile of raw pages.

Python library

TinySearch also works as a regular Python package:

pip install tinysuite-search

import asyncio
from tinysearch import research, to_prompt


async def main():
    evidence = await research("How does asyncio cancellation work?")

    print(evidence["sources"])
    print(to_prompt(evidence))


asyncio.run(main())

The Python API returns a stable, JSON-serializable evidence schema. Renderingthat evidence into an LLM prompt is explicit, so applications can store,inspect, transform, or budget the result first.

Search backends

TinySearch selects a web-search backend from config, so you can start with nosearch service and add one later without changing code.

• "ddgs" (native default): queries the ddgspackage's automatic backend selection in-process. No SearXNG deploymentrequired.
• "searxng" (Docker default): queries a self-hosted SearXNG instance. Fallsback to ddgs on backend failure unless search_backend_fallback is set tofalse.
• "duckduckgo": skips SearXNG and queries ddgs in DuckDuckGo-only mode.
• "auto": tries SearXNG, then falls back to ddgs on any backend failure.

Set the BRAVE_SEARCH_API_KEY environment variable to add Brave's officialWeb Search API as a keyed fallback for the ddgs and duckduckgo backends.Brave is only consulted when the primary call errors or returns no results.

Full key reference, SearXNG JSON-output setup, and Compose details live in theconfiguration reference.

Why TinySearch

• Built around token efficiency. Page selection and passage selectionhappen before content enters model context.
• Source-grounded by construction. Every evidence group stays attached toits originating URL.
• Useful without paid infrastructure. DDGS search and local ONNX embeddingsare the defaults.
• Bring your own stack when needed. SearXNG and OpenAI-compatible embeddingproviders remain optional.
• Works where agents already work. Use MCP over stdio, Streamable HTTP,Python, FastAPI, or Docker.
• Self-hosted and inspectable. No TinySearch account, analytics service, orhosted scraped-data cache.

Part of TinySuite

TinySuite is a product suite built around one idea:agents should spend tokens on useful work, not operational overhead.

Each tool focuses on a different part of the agent workflow and uses targetedtechniques to reduce unnecessary context before it reaches the model.TinySearch handles the web-research layer by turning pages into a small,ranked, source-grounded evidence packet.

Documentation

The README is the product overview. Detailed setup and operational materiallives in the TinySuite documentation:

• TinySearch overview and installation
• Configuration reference
• MCP tools
• Troubleshooting

The repository also contains an annotated example configuration atconfigs/tinysearch_config.json.

When not to use TinySearch

TinySearch is intentionally lightweight. Use a commercial search API,persistent crawler, or full search index when you need:

• guaranteed search coverage or an SLA
• large-scale or scheduled indexing
• long-term page storage and change history
• enterprise observability and access controls

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.14across Linux, macOS, and Windows.

Entrypoints

• tinysearch.research and tinysearch.scrape_url: structured Python API
• tinysearch.to_prompt: pure structured-evidence prompt renderer
• tinysearch mcp: stdio MCP server (also the no-argument default)
• tinysearch serve: Streamable HTTP MCP server
• tinysearch.servers.fastapi_server:app: optional FastAPI application

Community

Questions, ideas, and bug reports are welcome:

• Join the TinySearch Discord
• Open a GitHub issue
• Email the maintainer

Privacy and license

TinySearch reads public pages and returns selected excerpts to the callingclient. Search, crawling, local embeddings, and reranking can run withoutsending page content to an embedding provider. If you choose anOpenAI-compatible embedding backend, that provider receives the text sent forvectorization.

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