# Free Search [Health: Active] **Category:** 🔎 Search & Data Extraction **Repository:** https://github.com/sweetcornna/free-search-mcp **GitHub Stars:** 176 **Views:** 8 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/free-search ## Description No-API-key web search, page fetching and document reading across many engines. Local-first. ## Tools Capabilities this server exposes over MCP: - **search** — Run a multi-engine web search and return a ranked, deduplicated link list. Best for: - Discovery queries ("what is X", "find me X", "who is X"). - Getting a list of URLs you can hand to `fetch` / `fetch_batch` next. - Topics likely to be after your knowledge cutoff (use `freshness="week"`). - Filtering to specific domains (`include_domains=["python.org"]`) or a kind of source (`category="paper"` / `"finance"`, or a sub-group like `category="paper.biomed"` / `"finance.filings"`; see `engines()` for the full tree). - Looking a fact up at its registry, with no category needed: a current version or support end date ("latest fastapi version"), a CVE ("CVE-2024-3094": NVD record, OSV advisories, CISA exploited status), a forecast ("上海明天天气"), an exchange rate ("100 usd to cny": ECB, and the PBOC parity for 人民币), a coin price, a country indicator ("china gdp", "japan population"), public holidays ("2026年放假安排"), the current time in a city, a domain's expiry, a company's legal entity, an iOS app's version, Wikidata facts ("Shanghai population"). The source that fits the words joins the search and its record arrives as the first result with the publisher's date in `dated …`, so it can be cited without a fetch. Name the thing plainly. `category=` ("software", "security", "weather", "finance.fx", "stats", "calendar", "reference", "docs", "gov") asks the same sources explicitly. Not recommended for: - You already know the URL -> use `fetch` instead. - You want both links AND their full text in one call -> use `research`. - You want to query pages already in the local cache -> use `cache_search`. - Reading PDFs/DOCX from a known URL -> use `read_doc`. - Following one paper's references or citations -> use `paper_graph`. Returns: - markdown (default): numbered list of `n. title`, ``, snippet. About 40% fewer tokens than json. When an answer agent is configured (`SEARCH_MCP_AGENT_BACKEND`), a short sourced `## Answer` block sits above the list; it starts beside the engines and answers from the same result set. - json: dict with `results` (list of {title,url,snippet,engines,score}), `engines`, `cached`, optional `errors` map, optional `hint` string, and `agent` ({answer, backend, model, sources, elapsed_seconds} or {error}) when an answer agent is configured. `engines` is what was actually ASKED for this answer; each result's own `engines` is what found it. A default engine that failed recently is not asked and appears under `benched_engines` instead; a rescue pass that substituted a source appears as `rescued_via`. When the operator has signed in to an agent engine (`codex`), it searches beside the keyless engines and `agent_lane` reports it ({engines, answered, pending, errors, rate_limited, benched, left_out}; `left_out` lists an answer dropped as off-topic or unconfirmed); one still searching when the links return is merged into the cached result set, so the same call repeated later carries its results too. Common mistakes: - Answering from snippets. A snippet is an engine's summary of a page as it looked when crawled: it drops qualifiers and is often years old. Use `search` to find the URL, then read the page (`fetch`, `research`) for any date, amount, rule, deadline or number you will state. - Treating the `## Answer` block as verified. It is one small model's reading of the few pages below; read the source page yourself before acting on a deadline, price or rule. - Treating a result as recent because `freshness=` was set. The filter keeps undated results; the header says how many could be dated (`dated: 3/10`) and each result is marked `dated …`, `… (from snippet text)` or `undated`. - Passing a URL as `query`: that is `fetch`'s job. - Cranking `max_results` up hoping for better recall; engines cap around 10-20 each, anything beyond is duplicate noise (and 50 is the ceiling). - Naming engines by default. The default pool is already the set that works keylessly over plain HTTP, it benches an engine that starts failing and seats a reserve when it gets thin, and naming engines switches all of that, and `category=` routing, off. Name engines when you want a specific index: `engines=["so360","baidu"]` for Chinese-language sites, `engines=["brave"]` (needs the browser) for a second opinion. - Using `category="news"` for breaking news without also setting `freshness="day"`: the index lags by days. Args: query: Natural-language query (the same string a human would type). engines: Subset of `engines()`. None (recommended) = the health-aware default pool: duckduckgo, bing, yahoojp (Google's index) and anysearch, plus googlenews when `freshness` is "day"/"week", so360 and quark for a Chinese query and naver for a Korean one. max_results: Merged result count after dedup, clamped to 1-50. It is also the PER-ENGINE budget, so it multiplies across the fan-out; 5-20 is the useful range and anything past that is duplicate noise bought with real latency. Omit it for the configured default. use_cache: Reuse the last result for this exact (query, engines, max_results, AND all active filters: freshness, include/exclude domains, category, include/exclude text) within the cache TTL. Changing any filter is a different cache entry. False forces a re-fetch. max_age_hours: Treat cached results older than this as a read miss; a fresh result is ALWAYS written back to the cache regardless of this value, so caching is never disabled. Use 0 to force-refresh while keeping cache writes; None = use server default TTL (7 days). freshness: "day"|"week"|"month"|"year". Restricts to recent results. Best-effort: applied as an engine time-window param AND a client-side date check, but most HTML-engine results carry no parseable date, so undated results are kept rather than dropped (unknown != old). Treat it as a strong hint, not a hard filter; googlenews dates are exact. include_domains: List of domains to restrict to (e.g. ["python.org"]). exclude_domains: List of domains to exclude. category: Which KIND of source to search. The enum lists every value. A bare group widens: "paper" adds one specialist per sub-group to the default web pool. A dotted sub-group narrows to just the sources that index it ("paper.biomed" => the biomedical indexes only). It also RERANKS: engines that natively index the category count double in the fusion, so the filing outranks the commentary about it, and a record looked up by the query (a PyPI release, a CVE, an ECB rate, a forecast) counts five times, so it leads the list. Call `engines()` for the group -> sub-group -> engine tree with a line on each source. Two behaviours worth knowing: "image"/"dataset" REPLACE the web pool rather than augment it (a web engine cannot return an image file), and "news"/"paper"/"forum"/"github"/"blog" also filter general-web hits by hostname, so a strict category can thin those engines out. The specialists it routes to are exempt. include_text: Substring required in title or snippet (case-insensitive). exclude_text: Substring forbidden in title or snippet. format: "markdown" (default) or "json". - **fetch** — Fetch one URL: page text, or a description of a non-text resource. Handles any http(s) resource, not just HTML: - HTML pages -> reader-mode Markdown (nav/footer/scripts stripped). - PDF/DOCX/XLSX/PPTX/EPUB/CSV/code/archives -> parsed text (same engine as `read_doc`, which you should prefer when you need pagination). - Images, video, audio, fonts, opaque binaries -> a description (media type, byte size, dimensions, sha256), NOT the bytes. Best for: - You already have a URL (from `search`, the user, or your own knowledge) and need the actual page text. - Verifying a single claim by reading the source. - Checking what a resource IS before deciding to spend tokens on it. Not recommended for: - Multiple URLs at once -> use `fetch_batch` (concurrent, one round-trip). - "Search then read top N" -> use `research` (one call, not two). - Long documents you need to page through -> use `read_doc` (start/length). - You don't have a URL yet -> use `search` first. Returns: - markdown (default): a small header (URL, render method, token count) plus the cleaned page body. - json: {url, title, content, method, truncated, tokens_estimated, author, published_date, sitename}, plus {media_type, bytes_size, sha256, width, height} for non-text resources. - With `inline=True` on an image: the image itself, viewable by a vision-capable model. Common mistakes: - Passing a search query instead of a URL. - Using `render="http"` on a JS-only SPA: it returns near-empty content; use "auto" (default) or "browser". - Setting `inline=True` on a large image out of habit. A 1MB image costs well over a thousand tokens; fetch it plainly first and inline only if the description says it's worth looking at. - Forgetting that results are cached 7 days: use `force_refresh=True` or `max_age_hours=0` for a fresh pull. The header says `cached N days ago` when you are not looking at the live page; for deadlines, prices and anything else that moves, that is the cue to refresh. - Reading `no publication date found` as "recent". It means unknown. Args: url: Absolute http(s) URL. render: "auto" (try HTTP, fall back to stealth Chromium), "http" (fast, fails on JS), "browser" (slow, robust). force_refresh: Bypass the page cache entirely. max_age_hours: Treat cached pages older than this as a miss. 0 = same as force_refresh. None = server default TTL (7 days). inline: For images only. Returns the image itself instead of a description, so a vision-capable model can see it. Ignored for text resources. format: "markdown" or "json". - **fetch_batch** — Fetch a list of URLs in parallel. Per-URL failures do not raise. Best for: - 2+ URLs you want to read in one round-trip. - Reading the top N results of a previous `search` call. Not recommended for: - A single URL -> `fetch` (no list-wrapping overhead). - "Search and then read" -> `research` collapses both into one tool call. - PDFs/DOCX -> `read_doc` per file. Returns: - markdown (default): each page rendered as a Markdown section, separated by horizontal rules; failed URLs become inline error notes. - json: list[dict], one entry per URL, with `error` set on failures. Common mistakes: - Passing a single URL inside a 1-element list: use `fetch` directly. - Assuming an exception means the whole batch failed; check each item's `error` field instead. Args: urls: List of absolute http(s) URLs (max 20 per call). render: Same as `fetch`. format: "markdown" or "json". - **read_doc** — Read an http(s) document (or a sandboxed local file) into Markdown. Best for: - Remote PDFs and DOCX from an http(s) URL (parsed locally, no remote API). - Local PDF/DOCX/text/Markdown files, ONLY when local reads are enabled (see Security below). - Paginating through a long document via `start` / `length`. Not recommended for: - Arbitrary HTML web pages -> `fetch` does reader-mode cleanup that this tool does not. - Pages discovered through search -> `fetch` or `research`. Security (local files are sandboxed and OFF by default): - Local-file reads are DISABLED unless the server operator sets the SEARCH_MCP_DOCUMENT_ROOT env var to a directory. With it unset, a local path raises a "local file reads are disabled" error. Pass an http(s) URL instead, or ask the operator to enable the sandbox. - When enabled, `source` must resolve INSIDE that root; relative paths resolve against the root (not the process CWD) and any `..` traversal that escapes the root is rejected. `file://` URLs are always rejected. - Remote http(s) sources are unaffected by this setting. Returns: - markdown (default): rendered document text with a small header. - json: {content, title, format, total_chars, start, returned_chars, truncated}. Use `total_chars` and `returned_chars` to drive pagination. Common mistakes: - Calling this on a normal article URL: you'll get raw HTML noise. Use `fetch` instead. - Forgetting to advance `start` when paginating: next call should pass `start = previous_start + returned_chars`. - Passing a negative `length` (raises an error) or a `start` past the end (clamped to EOF: you'll get `returned_chars == 0`, `start == total_chars`, and `truncated == False`, which is the signal you've paged off the end). Args: source: http(s) URL, or a local path UNDER SEARCH_MCP_DOCUMENT_ROOT when local reads are enabled (disabled by default; see Security). start: Character offset to begin reading from. Default 0. Clamped into [0, total_chars]; a negative value is treated as 0. length: Max characters to return; None = read to end (still capped by the per-call max content size). Must be >= 0. A negative length is rejected with a ValueError. format: "markdown" or "json". - **research** — One-shot research: search the web, fetch the top results, return both. Best for: - Open-ended questions that need finding sources AND reading them ("what's new with X", "summarize the controversy around Y"). - Replacing a `search` + N x `fetch` chain with one call. - Producing a citable brief with [n]-style source references. Not recommended for: - You only need links -> `search` (cheaper, no fetching). - You only need to read one URL you already have -> `fetch`. - You want to query previously-fetched cached pages -> `cache_search`. - Checking or expanding one paper's citations -> `paper_graph`. Returns: - markdown (default): a "Research brief" with a Sources index then the full Markdown body of each fetched document, separated by horizontal rules; includes a token estimate. - json: {question, engines, sources:[{rank,title,url,snippet,...}], documents:[...], tokens_estimated, errors}. Common mistakes: - Using `depth=8` for a quick lookup: that's 8 page fetches, and 2-3 is almost always enough. - Calling `research` for a known URL: that is what `fetch` is for. - Forgetting that `fetch=False` returns sources only (much cheaper if the LLM only needs to pick which one to read). Args: question: What you want to know, in natural language. depth: How many top results to fetch (1-8). 3 is a good default. engines: Override the engine set (see `engines()` for names). Prefer `category=`. Naming engines turns category routing off. fetch: If False, return source list without reading them. freshness: "day"|"week"|"month"|"year". Restricts to recent results. Best-effort; undated results are kept rather than dropped. include_domains: Restrict to these domains (e.g. ["python.org"]). exclude_domains: Drop results from these domains. category: Which KIND of source to search; a bare group widens, a dotted sub-group narrows. Same values as `search`; see `engines()`. include_text: Substring required in title or snippet (case-insensitive). exclude_text: Substring forbidden in title or snippet. use_cache: Reuse cached search/page data within TTL. max_age_hours: Treat cached search results AND cached page bodies older than this as a read miss; fresh data is always written back. 0 = force-refresh both the engine search and every fetched page body; None = server default TTL (7 days). A non-zero value is honored for both halves (it used to be ignored for anything but 0). format: "markdown" or "json". - **paper_graph** — Follow the citations of ONE paper, and check whether it still stands. `search` finds papers that MENTION your words. This follows the edges instead: what a specific paper built on, and what has built on it since. Best for: - Checking a citation before repeating it: is the DOI real, and has the paper been retracted or corrected? - "What happened after this result": citing works come back ordered by how much the field cited them, so a 2019 paper leads to the current state of the art rather than to the most recent preprint about it. - Building a reading list backwards from one good paper. Not recommended for: - Finding papers by topic -> `search(category="paper")`, or a sub-group like `"paper.biomed"` / `"paper.cs"` / `"paper.preprint"`. - Reading the paper itself -> `read_doc` on the returned URL. Returns: - markdown (default): the paper with its retraction/correction notices, then "References" and "Cited by" sections. - json: {paper, references, citations, notes}, where `paper.crossref` carries `registered` and every post-publication `notices` entry. Common mistakes: - Passing a topic instead of a paper. A title resolves to its single best match; a phrase that names no specific paper resolves to the wrong one. - Reading an empty `citations` list as "uncited" when `notes` says the lookup was truncated. Args: paper: DOI (`10.1145/1571941.1572114`, or a doi.org URL), an OpenAlex ID (`W2148972377`), or the paper's exact title. direction: "both", "references" (what it cites) or "citations" (what cites it). limit: Max neighbours per direction, 1-50. format: "markdown" or "json". - **cache_search** — Full-text search over pages already fetched into the local SQLite FTS5 index. Best for: - Recalling something the user/agent fetched earlier in the conversation ("what did that Wikipedia page say about X"). - Avoiding re-fetching content already in the local cache. - Quick keyword grep across the corpus you've built up. Not recommended for: - Discovering new pages on the open web -> use `search` or `research`. - When the cache is empty (fresh install) -> `search`/`research` first to populate it. Returns: - markdown (default): a per-hit list of title, URL, and a `[bracket]`- highlighted snippet around the matched terms. - json: list of {url, title, snippet, author, date, sitename}. The last three are "" when the cached row predates metadata capture. Common mistakes: - Treating this like web search: it ONLY hits pages already in the local cache. If the user hasn't fetched anything, you'll get zero hits. - Using natural-language phrases without quoting them; FTS5 splits on whitespace as AND. For an exact phrase use `"like this"`. Args: query: FTS5 query. Bare terms = AND. Supports OR / NOT, prefix (`term*`), and phrase (`"exact phrase"`). limit: Max hits to return. format: "markdown" or "json". - **engines** — List the available sources, grouped by what they index. Best for: - Choosing a source deliberately: which one indexes filings, or preprints, or Chinese-language pages. - Checking a name before passing it to `engines=` on `search` / `research`. Not recommended for: - Calling on every search: the list is static, so read it once. Returns (markdown): a `group -> sub-group -> engine` tree, one line of description per engine. `group="paper"` restricts it to that group. Returns (json): `{"engines": [...names...], "taxonomy": {...}, "descriptions": {...}}`. Prefer `category=` over `engines=`. `category="paper"` WIDENS: it routes to one specialist per sub-group. A dotted sub-group NARROWS: `"paper.biomed"` queries only the biomedical indexes. Naming engines explicitly turns that routing off entirely, so reach for it only to force a specific source. Common mistakes: - Passing one of these names as `query`: they belong in `engines=`. - Passing a key-only engine with no key configured; it returns an actionable error, not results. - **compare** — Fetch 2-5 URLs concurrently and return per-URL excerpts so the LLM can compare them against a single question in one round trip. Best for: - Side-by-side product/feature/article comparisons. - "Compare X to Y" or "How does A differ from B" queries. - Triangulating a fact across multiple sources. Not recommended for: - >5 URLs -> use `fetch_batch`. - 1 URL -> use `fetch`. - Don't have URLs yet -> use `search` or `research` first. Returns: - markdown (default): a comparison brief with per-URL sections, each containing title, sitename, published date, and a smart-truncated excerpt. - json: {question, urls, excerpts:[{url, title, excerpt, ...}], tokens_estimated}. Common mistakes: - Asking `compare` to actually answer the question: it returns material, the LLM does the comparison. - Passing >5 URLs and expecting them all to fit in context: use `fetch_batch` for bulk reads. Args: question: The comparison question the LLM will answer using the returned excerpts. urls: 2-5 absolute http(s) URLs. format: "markdown" (default) or "json". - **extract_structured** — Pull JSON-LD, OpenGraph, Twitter cards, and microdata from a web page. Best for: - Product pages (price, currency, availability, brand, rating). - Article pages (author, publish date, image, headline). - Recipe / event / video pages where rich metadata IS the answer. - Cases where `fetch` returns prose but you need fields. Not recommended for: - Just reading a page -> use `fetch`. - PDFs / DOCX -> use `read_doc`. - Pages that don't publish schema.org metadata (most blogs): you'll get empty lists; fall back to `fetch`. Returns: - json: {url, json_ld:[], microdata:[], opengraph:[], rdfa:[]}. Twitter card meta tags are surfaced inside the `opengraph` list. - markdown (default): a flattened key/value view with each block printed as a JSON code block under its syntax heading. Common mistakes: - Calling on every URL "just in case": most sites have no structured data, and `fetch` is what you actually want. Args: url: Absolute http(s) URL. format: "markdown" (default) or "json". - **download** — Save a file from a URL to a local, auto-expiring download directory. Downloads are enabled by default and saved under `SEARCH_MCP_CACHE_DIR/downloads`. Set `SEARCH_MCP_DOWNLOAD_ENABLED=false` to disable them or `SEARCH_MCP_DOWNLOAD_DIR` to override the destination. Best for: - Keeping an actual file (installer, dataset, archive, image) rather than its text. - Handing a path to another tool that needs a real file on disk. Not recommended for: - Reading a document's contents -> use `read_doc`, which parses it without touching the filesystem. - Looking at a web page -> use `fetch`. - Viewing an image -> use `fetch(inline=True)`. Returns: - markdown (default): where the file was saved, its size and type. - json: {url, saved_path, media_type, bytes_size, sha256, expires_in_hours}. An expires_in_hours value of 0 means TTL cleanup is disabled. Retention: files older than SEARCH_MCP_DOWNLOAD_TTL_HOURS (default 24) are deleted before the next download and at startup. A value of 0 disables TTL cleanup. Otherwise, treat the path as short-lived and copy it elsewhere if you need to keep it. Args: url: Absolute http(s) URL of the file to save. format: "markdown" or "json". ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `uvx` (confidence: high): ```json "mcpServers": { "free-search": { "command": "uvx", "args": ["free-search-mcp"] } } ``` ## Documentation ## What Free Search does Free Search provides a local-first MCP interface for discovering and reading web content without requiring search API credentials. It combines several keyless search sources, merges and deduplicates their results, and can route queries toward source categories such as papers, finance, software, security, weather, datasets, and government information. The server also handles content after discovery. HTML pages are cleaned into reader-style Markdown, common office and document formats are parsed into text, and non-text resources can be described by type, size, dimensions, and SHA-256 hash. Search and fetch results are cached locally, allowing later full-text queries over previously fetched pages. ## How it works A typical workflow starts with `search`, which accepts a natural-language query and returns ranked links. The default engine selection is keyless and can adapt when a source becomes unavailable. `category`, domain filters, text filters, and best-effort freshness windows refine the search. Explicit engine selection is available when a particular index is needed; `engines` lists the available source tree. For an open-ended question, `research` combines discovery with fetching the top results and returns a citable brief. Known URLs should go to `fetch`, while multiple URLs can be handled concurrently with `fetch_batch` or compared with `compare`. Search and page data use a default seven-day cache, with refresh controls available for time-sensitive content. The server runs locally through the MCP client and uses Python 3.11 or newer. Browser-based rendering is optional: Chromium can be installed for JavaScript-heavy pages and browser-dependent engines, while ordinary HTTP retrieval works without it. ## Setup and configuration The package can be launched with `uv`, so a source checkout is not required. Claude Code and Codex support the repository's plugin installation flow. Claude Desktop and other MCP clients can also be configured to launch the server. Install Chromium only when browser rendering is needed: ```bash uvx --from free-search-mcp playwright install chromium ``` Optional settings control proxy use, cache and download locations, browser-agent behavior, local document access, and download retention. Local document reads are disabled unless `SEARCH_MCP_DOCUMENT_ROOT` points to a sandbox directory. Downloads are enabled by default and are stored in a cache download directory; downloaded files normally expire after 24 hours. ## Tools and capabilities - `search` queries multiple engines, applies filters, and returns ranked, deduplicated links. - `research` searches, fetches top results, and produces a source-backed brief in one call. - `fetch` reads a URL, parses documents, or describes binary and media resources. - `fetch_batch` retrieves up to 20 URLs concurrently. - `read_doc` parses PDFs, DOCX, XLSX, PPTX, EPUB, CSV, code, archives, HTML, text, and Markdown, with pagination support. - `paper_graph` follows a paper's references and citing works and reports retraction or correction notices. - `cache_search` runs FTS5 full-text queries over pages already fetched locally. - `compare` returns excerpts from two to five URLs for side-by-side analysis. - `extract_structured` extracts JSON-LD, OpenGraph, Twitter card, microdata, and RDFa metadata. - `download` saves a URL to a temporary local file. - `engines` exposes the available groups, subgroups, and source names. Markdown is the default output format; tools that support it can return JSON instead. A separate answer tool appears only when an answer backend is configured. ## Limitations and notes Search freshness is best effort because many HTML results have no parseable publication date. Undated results remain in the response, so dates, prices, deadlines, and other changing facts should be verified by fetching the source and refreshing cached data when necessary. `fetch` expects an absolute HTTP or HTTPS URL and is not the right tool for a search query. `read_doc` is intended for documents rather than normal article pages. Local file access is sandboxed and off by default. Browser rendering adds a Chromium dependency, and some engines or sites may require a proxy when they impose CAPTCHA, login, or IP restrictions. _Full upstream README: https://allmcps.com/mcp/free-search/readme_