Music: “Ethereal Space (cdk Mix)” by cdk, ccmixter.org/files/cdk/34151, licensed CC BY 3.0. free-search-mcp is a local-first Model Context Protocol server that needs no API key.
Claude Code
> /plugin marketplace add sweetcornna/free-search-mcp> /plugin install free-search@free-search-mcp
Codex
$ npx skills add sweetcornna/free-search-mcp -a codex
Cursor
$ npx skills add sweetcornna/free-search-mcp -a cursor
Gemini CLI
$ npx skills add sweetcornna/free-search-mcp -a gemini-cli
GitHub Copilot
$ copilot plugin marketplace add sweetcornna/free-search-mcp$ copilot plugin install free-search@free-search-mcp
OpenCode
$ npx skills add sweetcornna/free-search-mcp -a opencode
Windsurf
$ npx skills add sweetcornna/free-search-mcp -a windsurf
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.
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.
| Multi-engine | No API key | Smart fallback | PDF/DOCX | FTS5 cache | Filters | Trafilatura | LLM-tuned | |
|---|---|---|---|---|---|---|---|---|
nickclyde/duckduckgo-mcp-server | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ~ |
mrkrsl/web-search-mcp | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ~ |
Aas-ee/open-webSearch | ✓ | ✓ | ~ | ✗ | ✗ | ✗ | ✗ | ~ |
VincentKaufmann/noapi-google-search-mcp | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ~ |
| free-search-mcp | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
"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.
| Tool | Description |
|---|---|
search(query, ...filters) | Parallel multi-engine search, RRF-merged, title-fuzzy + host-canonical deduped, with optional extractive lead_snippet |
research(question, depth?, ...filters) | One-shot: search + fetch top N + return Markdown brief |
paper_graph(paper, direction?, limit?) | Walk one paper's citation graph: references, citing works ranked by influence, and Crossref retraction/correction notices. Takes a DOI, an OpenAlex ID, an exact title, or an arXiv reference (arXiv:1706.03762, an arxiv.org/abs/… URL, a 10.48550/arXiv.… DOI, or a bare id such as 1706.03762, 2401.12345v3 or hep-th/9901001 when it is the whole input) |
compare(question, urls=[2..5]) | Concurrent fetch of 2-5 URLs, side-by-side excerpts keyed by question |
fetch(url, render?, inline?, ...) | Fetch any resource: reader-mode Markdown for pages, parsed text for documents, or a description (type/size/dimensions/sha256) for images and binaries. inline=True returns the image itself for vision models |
fetch_batch(urls, ...) | Concurrent multi-URL fetch (max 20 per call) |
read_doc(source, start?, length?, ...) | Parse PDF / DOCX / XLSX / PPTX / EPUB / CSV / code / zip-tar / HTML / TXT / MD with pagination |
extract_structured(url, ...) | Pull JSON-LD / OpenGraph / Twitter cards / microdata via extruct. Long prose fields (articleBody and the like) are clipped, and the result says so in trimmed. This tool returns metadata; use fetch for the text |
cache_search(query, limit?, ...) | FTS5 search across previously fetched pages |
engines(group?) | The source tree (group, then sub-group, then engine), one line each. group is an enum of the groups that own engines, so a typo fails schema validation |
download(url, ...) | Save a file to ${SEARCH_MCP_CACHE_DIR}/downloads by default; files auto-delete after 24h. Set SEARCH_MCP_DOWNLOAD_ENABLED=false to disable it. |
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:
| Param | Values | Effect |
|---|---|---|
freshness | day / week / month / year | Only results from the last N. Results with no date are kept, and freshness_note says when that is most of them. day / week also add googlenews |
include_domains | ["python.org", "djangoproject.com"] | Restrict to these domains |
exclude_domains | ["pinterest.com"] | Remove these |
category | a group (paper, finance, news, software, security, weather, …) or a sub-group (paper.biomed, finance.filings, finance.fx, software.python, dataset.ml, …) | Routes to the sources that natively index that kind of thing; the enum in the tool schema lists every value |
include_text | "async" | Substring required in title/snippet |
exclude_text | "beginner" | Substring forbidden |
max_age_hours | 24 | Accept a cached answer only if it is younger than this. Default 7 days; the tightest of this, the freshness window's TTL, the 6-hour news cap and the category's own cap (weather, finance.fx 1 hour; software, security 6 hours) wins |
Output is Markdown by default, with provenance and a token estimate in the
header. format="json" returns structured data.
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.SEARCH_MCP_PROXY) is the fix for IP gating.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.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.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.
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:
| Where | How |
|---|---|
| Claude Desktop | open free-search-mcp-<version>.mcpb from the latest release |
| MCP Registry | io.github.sweetcornna/free-search-mcp |
| Claude Code, without the plugin | claude mcp add search -s user -- uvx free-search-mcp |
| Codex, without the plugin | codex mcp add search -- uvx free-search-mcp |
| Hermes Agent (the plugin) | hermes plugins install sweetcornna/free-search-mcp/plugins/free-search --enable |
| Any other MCP client | the stdio command uvx free-search-mcp |
| Docker | docker compose build, then docker compose run --rm search-mcp |
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.
codex and antigravityTwo 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.
codex | antigravity | |
|---|---|---|
| Searches with | OpenAI's web search, the one Codex uses | Google Search, run by a Gemini model |
| Account | a ChatGPT plan that includes Codex | a Google account with Antigravity |
| Each search counts against | the plan's Codex usage | the account's Antigravity quota |
| The provider allows it | yes | no, see the warning below |
| Opens a sign-in page by itself | on first use, over stdio on a desktop | never |
| Full guide, with 中文速览 | docs/CODEX_SEARCH.md | docs/ANTIGRAVITY_SEARCH.md |
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
antigravityonly with an account you accept that risk for.
Stars on GitHub
Indexes a codebase into a knowledge graph of symbols, calls and dependencies, so your coding agent can answer how code works, what a change will break and why a bug happens. Ask in plain language instead of grepping through files.
@abhigyanpatwariTeaches Claude Code to query MCP servers with the fastmcp CLI, listing the tools a server offers and calling them. Useful for wiring MCP servers into workflows.
@prefecthqn8n-MCP is an open-source MCP server that lets Claude, ChatGPT, Cursor, and other AI assistants operate n8n: read failed executions, edit workflows in place, validate and test them, manage credentials, and build new workflows.
@czlonkowskiAn MCP server and skill that lets an AI assistant publish to Xiaohongshu (小红书), either as an image-and-text post or as a long-form article, using content you supply or extracted from a web page URL.
@xpzouyingMusic: “Ethereal Space (cdk Mix)” by cdk, ccmixter.org/files/cdk/34151, licensed CC BY 3.0. free-search-mcp is a local-first Model Context Protocol server that needs no API key. Install it with the command on its page. It includes verified-research. Its skills do not fire on their own yet. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it