Skip to content
Back to search

free-search-mcp

Local-first, no-API-key MCP server for web search, fetch, and document reading. Multi-engine (DuckDuckGo, Mojeek, Startpage), smart Playwright fallback, FTS5 cache, LLM-tuned output.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/sweetcornna/free-search-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/sweetcornna/free-search-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sweetcornna--free-search-mcp/badge.svg)](/listings/sweetcornna--free-search-mcp)

HTML

<a href="/listings/sweetcornna--free-search-mcp"><img src="/api/listings/sweetcornna--free-search-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need [uv](https://docs.astral.sh/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`, `startpage`, `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](#install).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 27 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://json.schemastore.org/claude-code-marketplace-manifest.json",
  3. "name": "free-search-mcp",
  4. "owner": {
  5. "name": "ymylive",
  6. "url": "https://github.com/sweetcornna"
  7. },
  8. "metadata": {
  9. "description": "The free-search-mcp project's own marketplace. It holds one plugin: the keyless search MCP server, its verification skill and its quick-search agent."
  10. },
  11. "plugins": [
  12. {
  13. "name": "free-search",
  14. "source": "./plugins/free-search",
  15. "description": "Local-first web search, page fetching and document reading with no API key and no signup. Ships 11 MCP tools, a source-verification skill and a quick-search agent.",
  16. "keywords": [
  17. "mcp",
  18. "search",
  19. "web-search",
  20. "research",
  21. "fetch",
  22. "no-api-key",
  23. "agent-skills"
  24. ]
  25. }
  26. ]
  27. }
README.md · README · 410 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # free-search-mcp
  2. <!-- mcp-name: io.github.sweetcornna/free-search-mcp -->
  3. https://github.com/user-attachments/assets/354b522a-ef6b-4547-bb07-c80c6268a5e8
  4. <p align="center"><sub>Music: “Ethereal Space (cdk Mix)” by cdk, <a href="https://ccmixter.org/files/cdk/34151">ccmixter.org/files/cdk/34151</a>, licensed <a href="https://creativecommons.org/licenses/by/3.0/">CC BY 3.0</a>.</sub></p>
  5. [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  6. [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
  7. [![MCP](https://img.shields.io/badge/MCP-2026--07--28-purple.svg)](https://modelcontextprotocol.io/specification/2026-07-28)
  8. free-search-mcp is a local-first Model Context Protocol server that needs no
  9. API key. It lets any LLM (Claude, GPT, a local Ollama model, …) search the web,
  10. fetch and clean up pages, and read documents, and you never sign up for a
  11. search API.
  12. It combines ideas from several open-source MCP servers in one Python package,
  13. and adds the output shaping for LLMs and the reliability work that each of them
  14. lacked.
  15. ```text
  16. research("how does reciprocal rank fusion work", depth=3)
  17. ↓
  18. # Research brief: how does reciprocal rank fusion work
  19. _engines: duckduckgo, bing, yahoojp, anysearch · sources: 3 · ~3,400 tokens_
  20. ## Sources
  21. - [1] Reciprocal rank fusion | Elasticsearch Reference — <https://…>
  22. - [2] Hybrid Search Scoring (RRF) | Microsoft Learn — <https://…>
  23. - [3] RRF explained in 4 mins — Medium — <https://…>
  24. ## Documents
  25. …full Markdown bodies of each page, ready for the LLM to read…
  26. ```
  27. That was one tool call. It returned three sources with their full text, and no
  28. API key was involved.
  29. ## Quick start
  30. You need [uv](https://docs.astral.sh/uv/) and nothing else: no sign-up, no API
  31. key, no clone.
  32. In Claude Code, inside a session:
  33. ```text
  34. /plugin marketplace add sweetcornna/free-search-mcp
  35. /plugin install free-search@free-search-mcp
  36. ```
  37. In Codex:
  38. ```bash
  39. codex plugin marketplace add sweetcornna/free-search-mcp
  40. codex plugin add free-search@free-search-mcp
  41. ```
  42. (In Codex, a `[mcp_servers.search]` entry left in `~/.codex/config.toml` by an
  43. earlier `codex mcp add` silently shadows the plugin's server. Remove it with
  44. `codex mcp remove search`.)
  45. The plugin brings the 11 tools, the `verified-research` skill (how to check a
  46. snippet against its page and its date) and, in Claude Code, the
  47. `free-search:quick-search` agent, all pinned to one version.
  48. `/plugin update free-search` moves to the next release.
  49. Optionally, install Chromium once for the browser-rendered engines (`brave`,
  50. `zhihu`, …) and JavaScript-heavy pages. Everything else works
  51. without it, and a call that needs it returns this command as its error:
  52. ```bash
  53. uvx --from free-search-mcp playwright install chromium
  54. ```
  55. Claude Desktop, other clients, a source checkout and Docker are under
  56. [Install](#install).
  57. ## Why this exists
  58. | | Multi-engine | No API key | Smart fallback | PDF/DOCX | FTS5 cache | Filters | Trafilatura | LLM-tuned |
  59. |---|---|---|---|---|---|---|---|---|
  60. | `nickclyde/duckduckgo-mcp-server` | ✗ | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | ~ |
  61. | `mrkrsl/web-search-mcp` | ✓ | ✓ | ✓ | ✗ | ✗ | ✗ | ✗ | ~ |
  62. | `Aas-ee/open-webSearch` | ✓ | ✓ | ~ | ✗ | ✗ | ✗ | ✗ | ~ |
  63. | `VincentKaufmann/noapi-google-search-mcp` | ✗ | ✓ | ✓ | ✓ | ✓ | ✗ | ✗ | ~ |
  64. | **free-search-mcp** | **✓** | **✓** | **✓** | **✓** | **✓** | **✓** | **✓** | **✓** |
  65. "LLM-tuned" means Markdown-first output with token estimates, errors that name
  66. the next step, and a `research()` that turns a search and its fetches into one
  67. call. [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md) explains the less obvious
  68. columns.
  69. ## Tools (11)
  70. | Tool | Description |
  71. |---|---|
  72. | `search(query, ...filters)` | Parallel multi-engine search, RRF-merged, title-fuzzy + host-canonical deduped, with optional extractive `lead_snippet` |
  73. | `research(question, depth?, ...filters)` | One-shot: search + fetch top N + return Markdown brief |
  74. | `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) |
  75. | `compare(question, urls=[2..5])` | Concurrent fetch of 2-5 URLs, side-by-side excerpts keyed by question |
  76. | `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 |
  77. | `fetch_batch(urls, ...)` | Concurrent multi-URL fetch (max 20 per call) |
  78. | `read_doc(source, start?, length?, ...)` | Parse PDF / DOCX / XLSX / PPTX / EPUB / CSV / code / zip-tar / HTML / TXT / MD with pagination |
  79. | `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 |
  80. | `cache_search(query, limit?, ...)` | FTS5 search across previously fetched pages |
  81. | `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 |
  82. | `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. |
  83. There are also 5 MCP prompts and 2 resource templates (`cache://page/{url}`,
  84. `cache://search/{query_hash}`). A twelfth tool, `ask`, appears only when an
  85. answer backend is configured (see [Delegating a lookup](#delegating-a-lookup)).
  86. `search` and `research` take these filters:
  87. | Param | Values | Effect |
  88. |---|---|---|
  89. | `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` |
  90. | `include_domains` | `["python.org", "djangoproject.com"]` | Restrict to these domains |
  91. | `exclude_domains` | `["pinterest.com"]` | Remove these |
  92. | `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 |
  93. | `include_text` | `"async"` | Substring required in title/snippet |
  94. | `exclude_text` | `"beginner"` | Substring forbidden |
  95. | `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 |
  96. Output is Markdown by default, with provenance and a token estimate in the
  97. header. `format="json"` returns structured data.
  98. ### How a search runs
  99. - A search that names no engines asks a small keyless pool: `duckduckgo`,
  100. `bing`, `yahoojp` (Yahoo! JAPAN, the keyless route to Google's index) and
  101. `anysearch`. `googlenews` joins when recency is asked for, `so360` and
  102. `quark` when the query is written in Chinese, `naver` when it is written in
  103. Korean. Sources that only served a
  104. CAPTCHA or an empty shell (`mojeek`, `google`, `startpage`, `searx`,
  105. `sogou`) were removed rather than left to fail on every fresh process.
  106. - `category=` routes to sources that index that kind of thing (papers,
  107. filings, datasets, packages, CVEs, …). Record sources such as `pypi`, `nvd`
  108. or `openmeteo` also join by themselves when the question is one they can
  109. answer directly.
  110. - An engine that serves a CAPTCHA, a login wall or an off-topic page is
  111. benched, a reserve takes its seat, and the response says what happened. A
  112. proxy (`SEARCH_MCP_PROXY`) is the fix for IP gating.
  113. - Once you have signed in to `codex`, it searches beside those engines on
  114. every such search and its results join the same ranking (the
  115. [agent lane](#the-agent-lane)). The links never wait more than 6 s for it.
  116. - With an answer backend configured (`SEARCH_MCP_AGENT_BACKEND=api`,
  117. `claude-code` or `codex`), `search` also runs the answer agent beside the
  118. engines from the same result set and puts a short sourced answer above the
  119. links. `SEARCH_MCP_AGENT_IN_SEARCH=false` turns that off; `ask` stays
  120. available either way.
  121. - Every result says how old it is and where its date came from, so the agent
  122. can tell a lead from a checked fact.
  123. - `engines()` prints the whole source tree. `engines=["so360", "baidu"]` runs
  124. exactly the engines named.
  125. No engine that a search reaches by itself needs a key. The details, with
  126. measurements, are in [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md); walls and
  127. proxies in [docs/PROXY_AND_GATES.md](docs/PROXY_AND_GATES.md); a tour of the
  128. tools with examples in [docs/USAGE.md](docs/USAGE.md).
  129. ## Install
  130. The plugin in [Quick start](#quick-start) is the recommended path, because the
  131. server is pinned to the plugin's version and updates with it. The other routes
  132. run the same server:
  133. | Where | How |
  134. |---|---|
  135. | Claude Desktop | open `free-search-mcp-<version>.mcpb` from the [latest release](https://github.com/sweetcornna/free-search-mcp/releases/latest) |
  136. | MCP Registry | `io.github.sweetcornna/free-search-mcp` |
  137. | Claude Code, without the plugin | `claude mcp add search -s user -- uvx free-search-mcp` |
  138. | Codex, without the plugin | `codex mcp add search -- uvx free-search-mcp` |
  139. | Hermes Agent (the plugin) | `hermes plugins install sweetcornna/free-search-mcp/plugins/free-search --enable` |
  140. | Any other MCP client | the stdio command `uvx free-search-mcp` |
  141. | Docker | `docker compose build`, then `docker compose run --rm search-mcp` |
  142. A source checkout with Chromium, a smoke test and client registration in one
  143. step:
  144. ```bash
  145. curl -LsSf https://raw.githubusercontent.com/sweetcornna/free-search-mcp/main/scripts/install.sh | bash -s -- --client claude-code
  146. ```
  147. Over HTTP, `uvx free-search-mcp --transport streamable-http --port 8000`
  148. serves `http://127.0.0.1:8000/mcp`. That endpoint has no authentication and
  149. fetches any URL for whoever reaches it, so keep it on loopback or put an
  150. authenticating proxy in front.
  151. The JSON for Claude Desktop, Cursor, Cline, Continue and Zed, the installer's
  152. options and the plugin's token cost are in [docs/INSTALL.md](docs/INSTALL.md).
  153. Operating rules for agents are in [docs/AGENT_USAGE.md](docs/AGENT_USAGE.md).
  154. ## Search on your own account: `codex` and `antigravity`
  155. Two opt-in engines search on an account you sign in with instead of an API
  156. key. Neither is in any pool or route, and nothing changes for anyone who never
  157. signs in. Once you sign in to `codex`, it searches beside the keyless engines
  158. on every automatic search (the [agent lane](#the-agent-lane)); `antigravity`
  159. runs only when a call or `SEARCH_MCP_AGENT_ENGINES` names it.
  160. | | `codex` | `antigravity` |
  161. |---|---|---|
  162. | Searches with | OpenAI's web search, the one Codex uses | Google Search, run by a Gemini model |
  163. | Account | a ChatGPT plan that includes Codex | a Google account with Antigravity |
  164. | Each search counts against | the plan's Codex usage | the account's Antigravity quota |
  165. | The provider allows it | yes | no, see the warning below |
  166. | Opens a sign-in page by itself | on first use, over stdio on a desktop | never |
  167. | Full guide, with 中文速览 | [docs/CODEX_SEARCH.md](docs/CODEX_SEARCH.md) | [docs/ANTIGRAVITY_SEARCH.md](docs/ANTIGRAVITY_SEARCH.md) |
  168. > Warning: Google's Antigravity terms forbid using its sign-in from third-party
  169. > tools and name suspension of the Antigravity and Gemini CLI accounts as the
  170. > consequence, and Google has suspended accounts for it. Sign in to
  171. > `antigravity` only with an account you accept that risk for.
  172. ### 1. Sign in once
  173. Run the sign-in on the machine the server runs on:
  174. ```bash
  175. uvx --from free-search-mcp search-mcp-login codex # the ChatGPT page `codex login` shows
  176. uvx --from free-search-mcp search-mcp-login antigravity # prints the warning, then Google's consent page
  177. uvx --from free-search-mcp search-mcp-login status # account, plan, token expiry
  178. ```
  179. (`uv run search-mcp-login …` in a source checkout.) The settings page,
  180. `search-mcp-admin`, has the same Sign in / 登录 buttons. Tokens are stored in
  181. `~/.config/search-mcp/oauth/` (`0600`) and refreshed automatically. The plugin,
  182. `uvx` and the Desktop bundle all read that directory, so a running server picks
  183. up a new sign-in without a restart.
  184. - `codex` can skip this step: the first search that names it opens the sign-in
  185. page and finishes once you approve (stdio on a desktop only;
  186. `SEARCH_MCP_CODEX_AUTO_SIGNIN=false` turns it off). A machine already signed
  187. in to the Codex CLI can reuse that sign-in read-only with
  188. `search-mcp-login codex --use-codex-cli`.
  189. - `antigravity` signs in with Antigravity's own OAuth client, which is not
  190. shipped in this package. The sign-in reads it from the Antigravity app
  191. installed on the machine (checked on macOS). Without Antigravity installed,
  192. set `SEARCH_MCP_ANTIGRAVITY_CLIENT_ID` and
  193. `SEARCH_MCP_ANTIGRAVITY_CLIENT_SECRET`; a machine that has signed in keeps
  194. both in `~/.config/search-mcp/oauth/antigravity.json`.
  195. ### 2. Name the engine
  196. ```python
  197. search("rust 2024 edition changes", engines=["codex"])
  198. research("what changed in python 3.14 asyncio", engines=["antigravity"])
  199. search("rust 2024 edition changes", engines=["codex", "duckduckgo", "bing"])
  200. ```
  201. In Claude Code or Codex, ask for it in words ("search this with the codex
  202. engine"). Filters apply as usual, and results are cached like any other
  203. search. Measured on 2026-09-26, a `codex` search took about 3 s and an
  204. `antigravity` search 10 to 20 s.
  205. ### 3. Settings (all optional)
  206. | Var | Default | Meaning |
  207. |---|---|---|
  208. | `SEARCH_MCP_CODEX_MODEL`, `SEARCH_MCP_ANTIGRAVITY_MODEL` | `latest` | `latest` follows the account's model catalogue, so a new model is used once it is listed; a model name pins one |
  209. | `SEARCH_MCP_CODEX_TIMEOUT`, `SEARCH_MCP_ANTIGRAVITY_TIMEOUT` | `60` | seconds for one search |
  210. | `SEARCH_MCP_CODEX_AUTO_SIGNIN` | `true` | open the sign-in page on first use |
  211. | `SEARCH_MCP_AGENT_ENGINES` | `auto` | the agent lane: `auto` seats a signed-in `codex`; `off`; or a list such as `codex,antigravity` |
  212. | `SEARCH_MCP_AGENT_LANE_WAIT_SECONDS` | `6` | how long a search waits for the lane |
  213. | `SEARCH_MCP_AGENT_LANE_GRACE_SECONDS` | `2` | how much longer than the keyless engines it waits, once they have results |
  214. | `SEARCH_MCP_ANTIGRAVITY_CLIENT_ID`, `SEARCH_MCP_ANTIGRAVITY_CLIENT_SECRET` | read from the Antigravity install | for a machine without Antigravity; set both or neither |
  215. | `SEARCH_MCP_PROXY` | empty | the sign-in and the searches go through it |
  216. ### The agent lane
  217. A signed-in `codex` does not wait to be named. Every search that names no
  218. engines asks it at the same moment as the keyless pool, and its results are
  219. fused into the same ranking, so the agent search and the keyless search run in
  220. parallel and one answer comes back. The keyless pool keeps its breaker,
  221. reserves, routing and rescue, which naming `engines=["codex", ...]` would
  222. switch off.
  223. - The search waits for the lane at most 6 s from when the engines were asked
  224. (`SEARCH_MCP_AGENT_LANE_WAIT_SECONDS`), and at most 2 s past the keyless
  225. engines once they have results. A lane engine still searching then
  226. finishes in the background, and its results are merged into the cached
  227. result set, so the same search a little later returns them.
  228. - The lane never queues for a rate-limit token, a spent usage window benches
  229. it at once, and its problems are reported under `agent_lane`, never as a
  230. failed search.
  231. - `SEARCH_MCP_AGENT_ENGINES=off` turns it off; `codex,antigravity` adds
  232. `antigravity` to it.
  233. ### On a server, over SSH, or in Docker
  234. - Sign in with `--no-browser` (`search-mcp-login codex --no-browser`, or
  235. `antigravity --no-browser`), open the printed address in any browser, and
  236. approve. The browser then fails to load a `127.0.0.1:1455` or
  237. `localhost:51121` address; paste that whole address into the terminal.
  238. - Over `streamable-http`, `codex` never opens a sign-in page by itself, since
  239. it would open on the server. Sign in there with the command above first.
  240. - In Docker, point `SEARCH_MCP_CONFIG_DIR` at a mounted volume so the tokens
  241. outlive the container, and run the sign-in inside it with `--no-browser`.
  242. `antigravity` there needs the two client variables.
  243. `search-mcp-login logout codex` or `logout antigravity` deletes the stored
  244. tokens. To revoke Antigravity's access itself, remove it under "Third-party
  245. apps and services" in the Google account.
  246. ### When it does not work
  247. | The error says | Do this |
  248. |---|---|
  249. | `codex not configured` / `antigravity not configured` | no sign-in is stored on this machine; run the sign-in above |
  250. | `port 1455 and 1457 … are in use`, or port 51121 | another sign-in (`codex login`, an open sign-in page) holds the port; close it and retry |
  251. | the usage limit, quota or rate limit was reached | wait until the reset time the error gives; the keyless engines still work |
  252. | `needs Antigravity's OAuth client` | install Antigravity, or set the two client variables |
  253. | HTTP 403 `no valid license` from `antigravity` | set `SEARCH_MCP_ANTIGRAVITY_VERSION` to the installed Antigravity release; it can also mean Google restricted the account |
  254. | `has expired or was revoked` | sign in again |
  255. ## Optional: your own API key
  256. You do not need one, and agents should never ask for one. Six engines run
  257. only when a call names them and the operator has set their own key:
  258. | Engine | Provider | Key |
  259. |---|---|---|
  260. | `brave_api` | [Brave Search API](https://brave.com/search/api/) | `SEARCH_MCP_BRAVE_API_KEY` |
  261. | `serper` | [Serper](https://serper.dev) | `SEARCH_MCP_SERPER_API_KEY` |
  262. | `serpbase` | [SerpBase](https://serpbase.dev) | `SEARCH_MCP_SERPBASE_API_KEY` |
  263. | `tavily` | [Tavily](https://app.tavily.com) | `SEARCH_MCP_TAVILY_API_KEY` |
  264. | `google_cse` | [Google Custom Search](https://programmablesearchengine.google.com/) | `SEARCH_MCP_GOOGLE_CSE_API_KEY` + `SEARCH_MCP_GOOGLE_CSE_CX` |
  265. | `github_code` | [GitHub](https://github.com/settings/tokens) | `SEARCH_MCP_GITHUB_TOKEN` |
  266. Set a key as an environment variable or `.env` line, or on the local settings
  267. page:
  268. ```bash
  269. uv run search-mcp-admin # local settings / 本地设置 — http://127.0.0.1:8765
  270. ```
  271. (`uvx --from free-search-mcp search-mcp-admin` for a plugin or uvx install.)
  272. The page is bilingual (中英双语), binds to `127.0.0.1` only, applies a saved
  273. key without a restart, and never shows a stored value again. The walkthrough
  274. per provider is [docs/API_KEYS.md](docs/API_KEYS.md).
  275. ## Delegating a lookup
  276. Delegation keeps page text out of the caller's context and returns a short
  277. answer with dated sources. None of it is on by default:
  278. | You want | Use | It needs |
  279. |---|---|---|
  280. | The agent to search and read by itself | the tools, as installed | nothing |
  281. | Your host's own subagents to do the lookup | the `quick-search` agent definition | a host with subagents |
  282. | The server to dispatch through Claude Code | `SEARCH_MCP_AGENT_BACKEND=claude-code` | the `claude` CLI, logged in |
  283. | The server to dispatch through Codex | `SEARCH_MCP_AGENT_BACKEND=codex` | the `codex` CLI, logged in |
  284. | The server to call a model endpoint you choose | `SEARCH_MCP_AGENT_BACKEND=api` | an OpenAI-compatible or Anthropic-compatible URL |
  285. | Your own code to supply the model | `ask(question, answer_with=...)` in Python | nothing else |
  286. The settings, the agent files and measured timings are in
  287. [docs/DELEGATION.md](docs/DELEGATION.md).
  288. ## Configuration
  289. Nothing is required. Settings are `SEARCH_MCP_*` variables, read from the
  290. environment first, then `./.env`, then `~/.config/search-mcp/.env`
  291. (`SEARCH_MCP_CONFIG_DIR` moves that directory). The ones people change most:
  292. | Var | Default | Meaning |
  293. |---|---|---|
  294. | `SEARCH_MCP_PROXY` | empty | outbound proxy (`http`, `https` or `socks5`) for the engines, the browser and `fetch` |
  295. | `SEARCH_MCP_PROXY_ENGINES` | empty | proxy only these engines |
  296. | `SEARCH_MCP_DEFAULT_ENGINES` | `["duckduckgo","bing","yahoojp","anysearch"]` | the pool a search uses when it names no engines |
  297. | `SEARCH_MCP_REGION` | `us-en` | locale for engines that take one |
  298. | `SEARCH_MCP_CACHE_DIR` | `~/.cache/search-mcp` | search and page cache |
  299. | `SEARCH_MCP_TOOLS` | empty | register only these tools |
  300. Every setting is listed in [docs/CONFIGURATION.md](docs/CONFIGURATION.md) and
  301. documented in [.env.example](.env.example).
  302. ## Development
  303. ```bash
  304. git clone https://github.com/sweetcornna/free-search-mcp.git && cd free-search-mcp
  305. uv sync && uv run playwright install chromium
  306. uv run pytest -q # offline
  307. SEARCH_MCP_TEST_NETWORK=1 uv run pytest -v # live, hits the real web
  308. ```
  309. Running `claude` inside the checkout picks up the repo's `.mcp.json`, which
  310. starts the working tree's server. The architecture is in
  311. [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md#architecture), and cutting a
  312. release in [docs/RELEASING.md](docs/RELEASING.md).
  313. ## Credits
  314. This project builds on:
  315. - [`mrkrsl/web-search-mcp`](https://github.com/mrkrsl/web-search-mcp): the
  316. httpx-then-Playwright fetch strategy and the multi-engine fallback chain
  317. - [`Aas-ee/open-webSearch`](https://github.com/Aas-ee/open-webSearch):
  318. multi-engine breadth (Bing/DDG/Baidu/Brave/Startpage)
  319. - [`VincentKaufmann/noapi-google-search-mcp`](https://github.com/VincentKaufmann/noapi-google-search-mcp):
  320. anti-detection patterns (`navigator.webdriver`, UA, cookies), the SQLite
  321. FTS5 cache idea, and multi-format `read_document`
  322. - [`nickclyde/duckduckgo-mcp-server`](https://github.com/nickclyde/duckduckgo-mcp-server):
  323. per-engine rate limiting and LLM-friendly content cleanup
  324. - [Model Context Protocol](https://modelcontextprotocol.io/) and the
  325. [official Python SDK](https://github.com/modelcontextprotocol/python-sdk)
  326. ## License
  327. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.