# tinysearch **Category:** 💻 Developer Tools **Repository:** https://github.com/TinySuiteHQ/TinySearch **npm Downloads (last month):** 22 **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/tinysearch ## Description Self-hosted web research for MCP agents. ## Claude Desktop Quick Installation Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "tinysearch": { "command": "npx", "args": ["-y","tinysearch"] } } ``` ## Documentation & README # 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

[![Website](https://img.shields.io/badge/tinysuite.dev-home-000000?logo=googlechrome&logoColor=white)](https://tinysuite.dev) [![PyPI version](https://img.shields.io/pypi/v/tinysuite-search?label=pypi)](https://pypi.org/project/tinysuite-search/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Release](https://img.shields.io/github/v/release/TinySuiteHQ/TinySearch?label=release)](https://github.com/TinySuiteHQ/TinySearch/releases) [![Last Commit](https://img.shields.io/github/last-commit/TinySuiteHQ/TinySearch)](https://github.com/TinySuiteHQ/TinySearch/commits/main) [![Docker Pulls](https://img.shields.io/docker/pulls/marcellm01/tinysearch?label=docker%20pulls)](https://hub.docker.com/r/marcellm01/tinysearch) [![Discord](https://img.shields.io/badge/Discord-Join%20community-5865F2?logo=discord&logoColor=white)](https://discord.gg/NG6u2zamR) ![MCP Server](https://img.shields.io/badge/MCP-server-blue) ![FastAPI](https://img.shields.io/badge/FastAPI-supported-009688) 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](https://tinysuite.dev), a suite of focused tools designed to make agentic operations cheaper by minimizing token usage through smart retrieval, selection, and context-management techniques.

TinySearch returning source-grounded web evidence to an AI agent

## 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](https://tinysuite.dev/docs/tinysearch/) 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: ```mermaid 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. 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.

Benchmark: TinySearch uses 95% fewer tokens than a naive search-and-fetch agent across 8 research queries, cutting modeled input cost per 1,000 queries from $72.13 to $3.40 at $3 per million tokens

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. Reproduce or rerun it yourself: ```bash python scripts/benchmark_token_savings.py --json-out report.json ``` ## Quick start With [`uv`](https://docs.astral.sh/uv/) installed, add TinySearch to any MCP client: ```json { "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 and the legacy `research` tool also initialize the configured embedding model. Pre-warm both ahead of time if you will use those workflows: ```bash uvx --from "tinysuite-search[server]" tinysearch setup ```

TinySearch CLI setup and first run in a terminal

Prefer Docker, a remote MCP endpoint, or a source checkout? Follow the [installation guide](https://tinysuite.dev/docs/tinysearch/). ## Four MCP tools | Tool | Use it when | | --- | --- | | `search(query)` | You need fast, backend-ordered discovery without crawling or reranking | | `scrape_urls(items)` | You know one to five pages; each item may use `*` for its configured clean page-order token budget | | `get_current_datetime()` | A question depends on the current date or time | | `research(query)` | Legacy compatibility only; deprecated in favor of `search` followed by scraping | 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](https://tinysuite.dev/docs/tinysearch/mcp-tools/) 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. Successful MCP tool-result text is XML. A search result looks like this: ```xml Python asyncio cancellation Coroutines and Tasks https://docs.python.org/3/library/asyncio-task.html Tasks can be cancelled... ``` `scrape_urls` returns each page's selected Markdown chunks under one `` batch root, and `get_current_datetime` returns ``. Dynamic values are escaped so retrieved content cannot forge the XML boundaries around it. 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, and upstream dates 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. The deprecated MCP `research` tool retains the older all-in-one search, crawl, and rerank pipeline for compatibility. New MCP integrations should compose `search` with `scrape_urls` instead. ## Python library TinySearch also works as a regular Python package: ```bash pip install tinysuite-search ``` ```python import asyncio from tinysearch import scrape_urls, search async def main(): results = await search("Python async tasks") print(results["results"]) page_url = results["results"][0]["url"] evidence = await scrape_urls([{ "url": page_url, "query": "How does asyncio cancellation work?", }]) print(evidence["results"]) asyncio.run(main()) ``` The Python API returns stable, JSON-serializable results. `search` accepts a per-call `limit` from 1 to 50. `scrape_urls` accepts a per-call `max_tokens` budget (4,000 by default); omit an item's scrape query or use `"*"` for page-order mode. Rendering structured evidence into an LLM prompt is explicit, so applications can store, inspect, transform, or budget the result first. The optional FastAPI app mirrors these surfaces. `POST /search` and `POST /research` accept `output_format` (`prompt` or `json`) and always respond with JSON; prompt mode places rendered text in the `answer` field. `POST /scrape` accepts one to five `{ "url", "query" }` items and always returns structured per-item outcomes. The app also exposes `/health`, `/current_datetime`, and read-only `/config`; configuration writes require explicit environment opt-in. ## Search backends TinySearch selects a web-search backend from config, so you can start with no search service and add one later without changing code. - `"ddgs"` (native default): queries the [`ddgs`](https://pypi.org/project/ddgs/) package's automatic backend selection in-process. No SearXNG deployment required. - `"searxng"` (Docker default): queries a self-hosted SearXNG instance. Falls back to `ddgs` on backend failure unless `search_backend_fallback` is set to `false`. - `"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 official Web 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 the [configuration reference](https://tinysuite.dev/docs/tinysearch/configuration/). ## Why TinySearch - **Built around token efficiency.** Page selection and passage selection happen before content enters model context. - **Source-grounded by construction.** Every evidence group stays attached to its originating URL. - **Useful without paid infrastructure.** DDGS search and local ONNX embeddings are the defaults. - **Bring your own stack when needed.** SearXNG and OpenAI-compatible embedding providers 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, or hosted scraped-data cache. ## Part of TinySuite [TinySuite](https://tinysuite.dev) 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 targeted techniques 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 material lives in the TinySuite documentation: - [TinySearch overview and installation](https://tinysuite.dev/docs/tinysearch/) - [Configuration reference](https://tinysuite.dev/docs/tinysearch/configuration/) - [MCP tools](https://tinysuite.dev/docs/tinysearch/mcp-tools/) - [Troubleshooting](https://tinysuite.dev/docs/tinysearch/troubleshooting/) The repository also contains an annotated example configuration at [`configs/tinysearch_config.json`](configs/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 ```bash 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. ## Entrypoints - `tinysearch.search` and `tinysearch.scrape_urls`: structured Python API - `tinysearch.research`: legacy all-in-one structured Python research pipeline - `tinysearch.get_current_datetime`: structured UTC date and time - `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](https://discord.gg/NG6u2zamR) - [Open a GitHub issue](https://github.com/TinySuiteHQ/TinySearch/issues) - [Email the maintainer](mailto:hello.marcbuilds@gmail.com) ## Privacy and 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](LICENSE). Downloaded model weights remain subject to their respective model-card licenses. See [NOTICE](NOTICE) for third-party distribution details.