search

free-search-mcp

https://github.com/user-attachments/assets/354b522a-ef6b-4547-bb07-c80c6268a5e8

free-search-mcp is a local-first Model Context Protocol server that needs no API key. It lets any LLM (Claude, GPT, a local Ollama model, …) search the web, fetch and clean up pages, and read documents, and you never sign up for a search API.

It combines ideas from several open-source MCP servers in one Python package, and adds the output shaping for LLMs and the reliability work that each of them lacked.

research("how does reciprocal rank fusion work", depth=3)
   ↓
# Research brief: how does reciprocal rank fusion work
_engines: duckduckgo, bing, yahoojp, anysearch · sources: 3 · ~3,400 tokens_

## Sources
- [1] Reciprocal rank fusion | Elasticsearch Reference — <https://…>
- [2] Hybrid Search Scoring (RRF) | Microsoft Learn — <https://…>
- [3] RRF explained in 4 mins — Medium — <https://…>

## Documents
…full Markdown bodies of each page, ready for the LLM to read…

That was one tool call. It returned three sources with their full text, and no API key was involved.

Quick start

You need uv and nothing else: no sign-up, no API key, no clone.

In Claude Code, inside a session:

/plugin marketplace add sweetcornna/free-search-mcp
/plugin install free-search@free-search-mcp

In Codex:

codex plugin marketplace add sweetcornna/free-search-mcp
codex plugin add free-search@free-search-mcp

(In Codex, a [mcp_servers.search] entry left in ~/.codex/config.toml by an earlier codex mcp add silently shadows the plugin's server. Remove it with codex mcp remove search.)

The plugin brings the 11 tools, the verified-research skill (how to check a snippet against its page and its date) and, in Claude Code, the free-search:quick-search agent, all pinned to one version. /plugin update free-search moves to the next release.

Optionally, install Chromium once for the browser-rendered engines (brave, zhihu, …) and JavaScript-heavy pages. Everything else works without it, and a call that needs it returns this command as its error:

uvx --from free-search-mcp playwright install chromium

Claude Desktop, other clients, a source checkout and Docker are under Install.

Why this exists

"LLM-tuned" means Markdown-first output with token estimates, errors that name the next step, and a research() that turns a search and its fetches into one call. docs/HOW_IT_WORKS.md explains the less obvious columns.

Tools (11)

There are also 5 MCP prompts and 2 resource templates (cache://page/{url}, cache://search/{query_hash}). A twelfth tool, ask, appears only when an answer backend is configured (see Delegating a lookup).

search and research take these filters:

Output is Markdown by default, with provenance and a token estimate in the header. format="json" returns structured data.

How a search runs

• A search that names no engines asks a small keyless pool: duckduckgo, bing, yahoojp (Yahoo! JAPAN, the keyless route to Google's index) and anysearch. googlenews joins when recency is asked for, so360 and quark when the query is written in Chinese, naver when it is written in Korean. Sources that only served a CAPTCHA or an empty shell (mojeek, google, startpage, searx, sogou) were removed rather than left to fail on every fresh process.
• category= routes to sources that index that kind of thing (papers, filings, datasets, packages, CVEs, …). Record sources such as pypi, nvd or openmeteo also join by themselves when the question is one they can answer directly.
• An engine that serves a CAPTCHA, a login wall or an off-topic page is benched, a reserve takes its seat, and the response says what happened. A proxy (SEARCH_MCP_PROXY) is the fix for IP gating.
• Once you have signed in to codex, it searches beside those engines on every such search and its results join the same ranking (the agent lane). The links never wait more than 6 s for it.
• With an answer backend configured (SEARCH_MCP_AGENT_BACKEND=api, claude-code or codex), search also runs the answer agent beside the engines from the same result set and puts a short sourced answer above the links. SEARCH_MCP_AGENT_IN_SEARCH=false turns that off; ask stays available either way.
• Every result says how old it is and where its date came from, so the agent can tell a lead from a checked fact.
• engines() prints the whole source tree. engines=["so360", "baidu"] runs exactly the engines named.

No engine that a search reaches by itself needs a key. The details, with measurements, are in docs/HOW_IT_WORKS.md; walls and proxies in docs/PROXY_AND_GATES.md; a tour of the tools with examples in docs/USAGE.md.

Install

The plugin in Quick start is the recommended path, because the server is pinned to the plugin's version and updates with it. The other routes run the same server:

A source checkout with Chromium, a smoke test and client registration in one step:

curl -LsSf https://raw.githubusercontent.com/sweetcornna/free-search-mcp/main/scripts/install.sh | bash -s -- --client claude-code

Over HTTP, uvx free-search-mcp --transport streamable-http --port 8000 serves http://127.0.0.1:8000/mcp. That endpoint has no authentication and fetches any URL for whoever reaches it, so keep it on loopback or put an authenticating proxy in front.

The JSON for Claude Desktop, Cursor, Cline, Continue and Zed, the installer's options and the plugin's token cost are in docs/INSTALL.md. Operating rules for agents are in docs/AGENT_USAGE.md.

Search on your own account: codex and antigravity

Two opt-in engines search on an account you sign in with instead of an API key. Neither is in any pool or route, and nothing changes for anyone who never signs in. Once you sign in to codex, it searches beside the keyless engines on every automatic search (the agent lane); antigravity runs only when a call or SEARCH_MCP_AGENT_ENGINES names it.

Warning: Google's Antigravity terms forbid using its sign-in from third-party tools and name suspension of the Antigravity and Gemini CLI accounts as the consequence, and Google has suspended accounts for it. Sign in to antigravity only with an account you accept that risk for.