# tinysearch

Searches the web, ranks page passages locally, and returns selected text with source URLs. Use it when an agent needs evidence for web research.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 233
- Author: TinySuiteHQ
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/TinySuiteHQ/TinySearch
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/mcp/tinysuitehq-tinysearch

## What it does

tinysearch searches for pages and fetches them, then ranks passages locally before returning selected text and source URLs to an agent. Search uses DDGS, while local ranking combines BM25 with embeddings. The MCP server can be launched through `uvx`.

Page text stays unchanged: the server selects passages but does not rewrite or summarize them. Long pages can therefore produce less compact results than a separate model-based reduction step. DDGS works without a paid search API, but launching the server with `uvx` requires `uv`.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `MCP_TRANSPORT`, `TINYSEARCH_CONFIG_PATH`, `SEARXNG_URL`, `TINYSEARCH_EMBEDDING_BACKEND`, `TINYSEARCH_EMBEDDING_MODEL`, `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_RESOURCE_ATTRIBUTES` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env MCP_TRANSPORT=<MCP_TRANSPORT> --env TINYSEARCH_CONFIG_PATH=<TINYSEARCH_CONFIG_PATH> --env SEARXNG_URL=<SEARXNG_URL> --env TINYSEARCH_EMBEDDING_BACKEND=<TINYSEARCH_EMBEDDING_BACKEND> --env TINYSEARCH_EMBEDDING_MODEL=<TINYSEARCH_EMBEDDING_MODEL> --transport stdio tinysuitehq-tinysearch -- uvx tinysuite-search
```
Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-search <command>

### Codex

**Platform CLI**
```bash
codex mcp add tinysuitehq-tinysearch --env MCP_TRANSPORT=<MCP_TRANSPORT> --env TINYSEARCH_CONFIG_PATH=<TINYSEARCH_CONFIG_PATH> --env SEARXNG_URL=<SEARXNG_URL> --env TINYSEARCH_EMBEDDING_BACKEND=<TINYSEARCH_EMBEDDING_BACKEND> --env TINYSEARCH_EMBEDDING_MODEL=<TINYSEARCH_EMBEDDING_MODEL> -- uvx tinysuite-search
```
Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-search <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "tinysuitehq-tinysearch": {
            "command": "uvx",
            "args": [
                "tinysuite-search"
            ],
            "env": {
                "MCP_TRANSPORT": "<MCP_TRANSPORT>",
                "TINYSEARCH_CONFIG_PATH": "<TINYSEARCH_CONFIG_PATH>",
                "SEARXNG_URL": "<SEARXNG_URL>",
                "TINYSEARCH_EMBEDDING_BACKEND": "<TINYSEARCH_EMBEDDING_BACKEND>",
                "TINYSEARCH_EMBEDDING_MODEL": "<TINYSEARCH_EMBEDDING_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-search <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "tinysuitehq-tinysearch": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "tinysuite-search"
            ],
            "env": {
                "MCP_TRANSPORT": "<MCP_TRANSPORT>",
                "TINYSEARCH_CONFIG_PATH": "<TINYSEARCH_CONFIG_PATH>",
                "SEARXNG_URL": "<SEARXNG_URL>",
                "TINYSEARCH_EMBEDDING_BACKEND": "<TINYSEARCH_EMBEDDING_BACKEND>",
                "TINYSEARCH_EMBEDDING_MODEL": "<TINYSEARCH_EMBEDDING_MODEL>"
            }
        }
    }
}
```
Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-search <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MCP_TRANSPORT=<MCP_TRANSPORT> -e TINYSEARCH_CONFIG_PATH=<TINYSEARCH_CONFIG_PATH> -e SEARXNG_URL=<SEARXNG_URL> -e TINYSEARCH_EMBEDDING_BACKEND=<TINYSEARCH_EMBEDDING_BACKEND> -e TINYSEARCH_EMBEDDING_MODEL=<TINYSEARCH_EMBEDDING_MODEL> tinysuitehq-tinysearch uvx tinysuite-search
```
Replace <…> with your own values. 8 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from tinysuite-search <command>

## When to use it
- find web sources for a research question
- select relevant passages from fetched pages
- return source-linked evidence to an agent
- reduce the web text sent into an agent's context

## Example prompts
- Search the web for material on MCP server setup in Codex and return sourced passages.
- Find pages about local search reranking and collect evidence from them.
- Fetch these URLs, select useful passages, and include their source links.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74559
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md