Fast discovery search and self-hosted web research for MCP agents.
io.github.TinySuiteHQ/tinysearch (MCP)
TinySearch provides fast discovery search and self-hosted web research for MCP agents. It searches, crawls, and reranks web results locally, then returns only the evidence intended for use in an agent’s context rather than full webpages.
🛠️ Key Features
Fast discovery search
Self-hosted web research
Local web search, crawling, and reranking
Returns selected evidence for agent context
Description: “Spend tokens on answers, not webpages.”
🚀 Use Cases
Supporting MCP agents with web research
Providing prioritized, context-ready evidence from the web
⚡ Developer Benefits
Reduces token use by returning evidence rather than webpages
Improves relevance via crawling and reranking before context is assembled
⚠️ Limitations
Based on available data, no specific restrictions, configuration details, or tool list are provided in the provided excerpt.
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.
Quick start
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; the installation guide covers it.
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, and focused scraping also initializes the configured embedding model. Pre-warm both ahead of time if you will use those workflows:
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.
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.
Install
Configuration
Environment variables
MCP_TRANSPORT
MCP transport to serve: stdio (default), sse, or streamable-http.
TINYSEARCH_CONFIG_PATH
Path to a tinysearch_config.json inside the container, for overriding search/embedding defaults.
SEARXNG_URL
SearXNG search endpoint URL. Only needed if not using the bundled Compose SearXNG service.
TINYSEARCH_EMBEDDING_BACKEND
Embedding implementation: onnx (default) or openai_compatible.
TINYSEARCH_EMBEDDING_MODEL
Local ONNX preset (fast, balanced, quality) or a Hugging Face ONNX repository id.
OTEL_SERVICE_NAME
OpenTelemetry service.name resource attribute; defaults to tinysearch.
OTEL_EXPORTER_OTLP_ENDPOINT
Common OTLP endpoint for optional TinySearch traces and metrics.
OTEL_EXPORTER_OTLP_PROTOCOL
OTLP transport: http/protobuf (default) or grpc.
OTEL_EXPORTER_OTLP_HEADERSsecret
Optional authentication or routing headers for the OTLP exporter.
OTEL_RESOURCE_ATTRIBUTES
Additional standard OpenTelemetry resource attributes.
OTEL_TRACES_EXPORTER
Set to otlp to enable traces explicitly or none to disable them.
OTEL_METRICS_EXPORTER
Set to otlp to enable metrics explicitly or none to disable them.