TinySearch docs

Self-hosted web research for MCP agents.

TinySearch searches the web, crawls relevant pages, chunks content, reranks results, and returns a compact source-grounded prompt instead of raw webpages.

Fast path

Install, connect, research.

Use TinySearch when an MCP client needs web research but you do not want to dump full pages into the model context.

MCP endpointhttp://localhost:8000/mcp

Docker install

Start TinySearch with SearXNG.

The fastest path is Docker Compose. It runs TinySearch with a bundled SearXNG service and exposes Streamable HTTP.

docker compose -f "https://github.com/MarcellM01/TinySearch.git#main:compose.quickstart.yaml" up -d

Client setup

Connect your MCP client.

Point your client at the Streamable HTTP server.

{
  "mcpServers": {
    "tinysearch": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Optional source run

Run from source when you need stdio.

Use this path for local development or stdio-only clients.

git clone https://github.com/MarcellM01/TinySearch
cd TinySearch
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

{
  "mcpServers": {
    "tinysearch": {
      "command": "/absolute/path/to/TinySearch/.venv/bin/python",
      "args": ["/absolute/path/to/TinySearch/servers/mcp_server.py"]
    }
  }
}

Shutdown

Stop the stack later.

Bring the Docker services down when you are done testing.

docker compose -f "https://github.com/MarcellM01/TinySearch.git#main:compose.quickstart.yaml" down

Reference guide

Use these when a setup step needs more detail.

The main path above gets TinySearch running. The sections below explain what each part means, how to adjust it, and where to look if something fails.

Step 01Docker setup

What the Compose command starts and where the MCP endpoint lives.

After installConfiguration

Settings for search backend, chunking, quotas, and pipeline behavior.

Search backendSearXNG backend

Why SearXNG is bundled and what to check when using your own instance.

Step 02Tools

What your MCP client can call once TinySearch is connected.

First testExamples

Small calls to confirm the tools are wired up correctly.

If stuckTroubleshooting

Connection, SearXNG, model download, and crawl safety checks.

Supports Step 01

Docker setup

Docker pulls marcellm01/tinysearch:latest automatically if the image is not already local. The HTTP MCP endpoint is /mcp; SSE is available at/mcp/sse.

After install

Configuration

TinySearch reads research settings from configs/research_config.json. Common settings include the search backend, SearXNG URL, fallback behavior, embedding model, chunking, source quotas, and pipeline timeout.

Search backend

SearXNG backend

TinySearch defaults to a SearXNG-compatible JSON endpoint. The bundled Compose files enable a local SearXNG service so the stack works out of the box. If you point TinySearch at your own SearXNG instance, ensure JSON output is enabled.

Supports Step 02

Tools

research(query)

Use this when the agent needs to discover relevant URLs. TinySearch searches, ranks, crawls, chunks, reranks, and returns compact evidence.

scrape_url(url, query)

Use this when the user already provided a URL or when research found a page that should be inspected directly.

get_current_datetime()

Use this before time-sensitive research so the agent has current date context.

First test

Examples

research("What changed in the latest TinySearch release?")
scrape_url("https://github.com/MarcellM01/TinySearch", "What MCP tools does it expose?")
get_current_datetime()

If stuck

Troubleshooting

If the MCP client cannot connect, verify Docker is running and the endpoint is http://localhost:8000/mcp.
If SearXNG returns HTML, enable JSON output in the SearXNG configuration.
If research is slow on first run, allow time for the embedding model to download.
If a site is unsafe or unsupported, TinySearch may reject the URL before crawling.

View TinySearch on GitHub