Free Search

free-search-mcp

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

_{音乐：“Ethereal Space (cdk Mix)”，由 cdk 创作，ccmixter.org/files/cdk/34151，采用 CC BY 3.0 许可。}

free-search-mcp 是一个本地优先的 Model Context Protocol 服务，无需 API 密钥。它让任何大模型（Claude、GPT、本地 Ollama 模型等）都能搜索网络、获取并清理网页，以及读取文档，而且无需注册搜索 API 账号。

它将多个开源 MCP 服务的思路整合到一个 Python 包中，并补上了它们各自欠缺的面向大模型的输出优化和可靠性改进。

research("how does reciprocal rank fusion work", depth=3)
   ↓
# Research brief: how does reciprocal rank fusion work
_engines: duckduckgo, bing, 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…

一次工具调用就完成了。它返回了三个来源及其全文，而且没有用到 API 密钥。

快速开始

你只需要 uv，不需要其他东西：无需注册、无需 API 密钥，也无需克隆仓库。

在 Claude Code 中，打开一个会话并输入：

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

在 Codex 中：

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

（在 Codex 中，若先前运行 codex mcp add 后，~/.codex/config.toml 中仍留有 [mcp_servers.search] 条目，它会静默覆盖插件的服务。运行 codex mcp remove search 将其移除。）

该插件包含 11 个工具、verified-research 技能（介绍如何根据网页及其日期核验片段），以及在 Claude Code 中提供的 free-search:quick-search Agent，所有内容均固定为同一版本。 /plugin update free-search 会升级到下一个版本。

你也可以选择安装一次 Chromium，以支持通过浏览器渲染的搜索引擎（brave、startpage、zhihu 等）和 JavaScript 内容较多的网页。其他所有功能无需 Chromium；需要它的调用会在出错时返回以下命令：

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

Claude Desktop、其他客户端、源码检出和 Docker 的安装方法，请参阅安装。

为什么要开发它

	多引擎	无需 API 密钥	智能回退	PDF/DOCX	FTS5 缓存	过滤器	Trafilatura	面向大模型优化
nickclyde/duckduckgo-mcp-server	✗	✓	✗	✗	✗	✗	✗	~
mrkrsl/web-search-mcp	✓	✓	✓	✗	✗	✗	✗	~
Aas-ee/open-webSearch	✓	✓	~	✗	✗	✗	✗	~
VincentKaufmann/noapi-google-search-mcp	✗	✓	✓	✓	✓	✗	✗	~
free-search-mcp	✓	✓	✓	✓	✓	✓	✓	✓

“面向大模型优化”指以 Markdown 为先的输出、Token 数量估算、指出下一步操作的错误提示，以及可将搜索及其网页获取整合为一次调用的 research()。docs/HOW_IT_WORKS.md 介绍了不太直观的列。

工具（11）

工具	描述
search(query, ...filters)	并行多引擎搜索，使用 RRF 合并结果，按标题模糊匹配和规范化主机名去重，可选提供提取式 lead_snippet
research(question, depth?, ...filters)	一步完成：搜索 + 获取排名靠前的 N 个结果 + 返回 Markdown 简报
paper_graph(paper, direction?, limit?)	遍历一篇论文的引用图：参考文献、按影响力排序的引用作品，以及 Crossref 撤稿／更正通知。接受 DOI、OpenAlex ID、精确标题或 arXiv 引用（arXiv:1706.03762、arxiv.org/abs/… URL、10.48550/arXiv.… DOI，或单独作为完整输入的裸 ID，例如 1706.03762、2401.12345v3 或 hep-th/9901001）
compare(question, urls=[2..5])	并发获取 2 到 5 个 URL，并根据问题提供并列摘录
fetch(url, render?, inline?, ...)	获取任意资源：网页以阅读模式 Markdown 返回，文档返回解析后的文本，图像和二进制文件返回描述（类型／大小／尺寸／sha256）。inline=True 会返回图像本身，供视觉模型使用
fetch_batch(urls, ...)	并发获取多个 URL（每次最多 20 个）
read_doc(source, start?, length?, ...)	分页解析 PDF / DOCX / XLSX / PPTX / EPUB / CSV / 代码 / zip-tar / HTML / TXT / MD
extract_structured(url, ...)	通过 extruct 提取 JSON-LD / OpenGraph / Twitter 卡片 / 微数据。较长的文本字段（例如 articleBody）会被截断，结果会在 trimmed 中说明。此工具返回元数据；要获取文本，请使用 fetch
cache_search(query, limit?, ...)	在先前获取的网页中进行 FTS5 搜索
engines(group?)	来源树（依次为组、子组和引擎），每行一个。group 是拥有引擎的组之一；输入错误会导致架构验证失败
download(url, ...)	默认将文件保存到 ${SEARCH_MCP_CACHE_DIR}/downloads；文件会在 24 小时后自动删除。设置 SEARCH_MCP_DOWNLOAD_ENABLED=false 可禁用此功能。

此外还有 5 个 MCP 提示词和 2 个资源模板（cache://page/{url}、 cache://search/{query_hash}）。第 12 个工具 ask 仅在配置了答案后端时出现（参见委托查询）。

search 和 research 接受以下筛选条件：

参数	值	效果
freshness	day / week / month / year	仅返回最近 N 天内的结果。没有日期的结果仍会保留；如果这类结果占多数，freshness_note 会予以说明。day / week 还会添加 googlenews
include_domains	["python.org", "djangoproject.com"]	将结果限制在这些域名内
exclude_domains	["pinterest.com"]	排除这些域名
category	某个组（paper、finance、news、software、security、weather 等）或子组（paper.biomed、finance.filings、finance.fx、software.python、dataset.ml 等）	将请求路由到原生索引此类内容的来源；工具架构中的枚举列出了所有可用值
include_text	"async"	标题／摘要中必须包含的子字符串
exclude_text	"beginner"	标题／摘要中不得包含的子字符串
max_age_hours	24	仅当缓存答案的生成时间早于此时长时才接受。默认值为 7 天；此值、freshness 时间窗口的 TTL、新闻 6 小时上限，以及类别自身的上限（weather、finance.fx 为 1 小时；software、security 为 6 小时）中最严格的限制优先

默认以 Markdown 格式输出，并在页眉中包含来源信息和令牌估算。format="json" 返回结构化数据。

搜索如何运行

• 未指定引擎的搜索会询问一个小型免密钥池：duckduckgo、 bing、anysearch 和 mojeek。要求近期内容时会加入 googlenews， 查询使用中文时会加入 so360。
• category= 会将搜索路由到索引此类内容的来源（论文、 备案文件、数据集、软件包、CVE 等）。如果问题可由记录来源直接回答， pypi、nvd 或 openmeteo 等也会自行加入。
• 如果某个引擎出现 CAPTCHA、登录墙或无关页面，就会被暂时停用，由备用引擎接替， 并在响应中说明情况。IP 访问受限时，可通过代理（SEARCH_MCP_PROXY）解决。
• 每条结果都会说明其时效以及日期来源，方便 Agent 区分线索和已核实的事实。
• engines() 会打印完整的来源树。engines=["so360", "baidu"] 则只运行指定的引擎。

搜索自行访问的引擎都无需密钥。详细说明和测量数据见 docs/HOW_IT_WORKS.md；关于访问墙和代理的说明见 docs/PROXY_AND_GATES.md；工具及示例介绍见 docs/USAGE.md。

安装

快速开始中的插件是推荐方式，因为服务会固定为插件对应的版本，并随插件一起更新。其他方式运行的也是同一个服务：

位置	方式
Claude Desktop	打开 最新版本中的 free-search-mcp-<version>.mcpb
MCP Registry	io.github.sweetcornna/free-search-mcp
Claude Code，不使用插件	claude mcp add search -s user -- uvx free-search-mcp
Codex，不使用插件	codex mcp add search -- uvx free-search-mcp
Hermes Agent（插件）	hermes plugins install sweetcornna/free-search-mcp/plugins/free-search --enable
任何其他 MCP 客户端	stdio 命令 uvx free-search-mcp
Docker	执行 docker compose build，然后执行 docker compose run --rm search-mcp

一步完成检出源代码、安装 Chromium、运行冒烟测试并注册客户端：

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

通过 HTTP 运行时，uvx free-search-mcp --transport streamable-http --port 8000 会提供 http://127.0.0.1:8000/mcp。该端点没有身份验证，任何访问者都可以用它获取任意 URL，因此请将其限制在 loopback，或在前面放置一个需要身份验证的代理。

Claude Desktop、Cursor、Cline、Continue 和 Zed 的 JSON 配置、安装程序选项以及插件的令牌成本，见 docs/INSTALL.md。Agent 的操作规则见 docs/AGENT_USAGE.md。

使用自己的账户搜索：codex 和 antigravity

两个可选引擎可使用你登录的账户进行搜索，而不需要 API 密钥。它们都不属于任何搜索池或路由：只有调用明确指定时才会使用，未登录的用户不会受到任何影响。

	codex	antigravity
搜索方式	OpenAI 的网页搜索，即 Codex 使用的搜索	由 Gemini 模型运行的 Google 搜索
账户要求	包含 Codex 使用额度的 ChatGPT 套餐	已开通 Antigravity 的 Google 账户
每次搜索计入	套餐的 Codex 使用额度	账户的 Antigravity 配额
提供商是否允许	是	否，见下方警告
是否会自行打开登录页面	首次使用时，通过桌面上的 stdio 打开	从不
完整指南，含中文速览	docs/CODEX_SEARCH.md	docs/ANTIGRAVITY_SEARCH.md

警告：Google 的 Antigravity 条款禁止从第三方工具登录，并指出可能因此暂停 Antigravity 和 Gemini CLI 账户；Google 已经因此暂停过账户。只有在你愿意承担风险的账户上登录 antigravity。

1. 登录一次

在运行服务的机器上执行登录：

uvx --from free-search-mcp search-mcp-login codex         # the ChatGPT page `codex login` shows
uvx --from free-search-mcp search-mcp-login antigravity   # prints the warning, then Google's consent page
uvx --from free-search-mcp search-mcp-login status        # account, plan, token expiry

（在源码检出目录中运行 uv run search-mcp-login …。）设置页面 search-mcp-admin 上也有相同的 Sign in / 登录按钮。令牌存储在 ~/.config/search-mcp/oauth/（0600）中，并会自动刷新。插件、 uvx 和 Desktop 安装包都会读取该目录，因此正在运行的服务无需重启即可 获取新的登录信息。

• codex 可以跳过此步骤：首次搜索时，只要指定它，就会打开登录 页面，并在你批准后完成（仅限桌面上的 stdio； SEARCH_MCP_CODEX_AUTO_SIGNIN=false 可关闭此功能）。已登录 Codex CLI 的机器可以通过 search-mcp-login codex --use-codex-cli 以只读方式复用该登录信息。
• antigravity 使用 Antigravity 自己的 OAuth 客户端，本软件包不 随附该客户端。登录时会从机器上安装的 Antigravity 应用读取它（已在 macOS 上 验证）。如果未安装 Antigravity，请设置 SEARCH_MCP_ANTIGRAVITY_CLIENT_ID 和 SEARCH_MCP_ANTIGRAVITY_CLIENT_SECRET；已完成登录的机器会将 这两个值保存在 ~/.config/search-mcp/oauth/antigravity.json 中。

2. 指定引擎

search("rust 2024 edition changes", engines=["codex"])
research("what changed in python 3.14 asyncio", engines=["antigravity"])
search("rust 2024 edition changes", engines=["codex", "duckduckgo", "bing"])

在 Claude Code 或 Codex 中，用文字请求使用它（“用 codex 引擎搜索此内容”）。筛选条件照常生效，结果也会像其他搜索一样缓存。根据 2026-09-26 的测量，codex 搜索耗时约 3 s，antigravity 搜索耗时 10 到 20 s。

3. 设置（均为可选）

变量	默认值	含义
SEARCH_MCP_CODEX_MODEL、SEARCH_MCP_ANTIGRAVITY_MODEL	latest	latest 会跟随账户的模型目录，因此新模型列出后就会使用；指定模型名称则会固定使用该模型
SEARCH_MCP_CODEX_TIMEOUT、SEARCH_MCP_ANTIGRAVITY_TIMEOUT	60	单次搜索的秒数
SEARCH_MCP_CODEX_AUTO_SIGNIN	true	首次使用时打开登录页面
SEARCH_MCP_ANTIGRAVITY_CLIENT_ID、SEARCH_MCP_ANTIGRAVITY_CLIENT_SECRET	从 Antigravity 安装中读取	适用于未安装 Antigravity 的机器；两个值必须同时设置或都不设置
SEARCH_MCP_PROXY	空	登录和搜索都通过此代理进行

在服务端、通过 SSH 或在 Docker 中

• 使用 --no-browser 登录（search-mcp-login codex --no-browser，或 antigravity --no-browser），在任意浏览器中打开打印出的地址并 批准。随后浏览器会无法加载 127.0.0.1:1455 或 localhost:51121 地址；将完整地址粘贴到终端中。
• 通过 streamable-http 使用时，codex 不会自行打开登录页面，因为 登录页面会在服务端打开。请先在服务端运行上述命令登录。
• 在 Docker 中，将 SEARCH_MCP_CONFIG_DIR 指向已挂载的卷，以便令牌在容器 销毁后仍保留；并在容器内使用 --no-browser 登录。 在 Docker 中使用 antigravity 还需要设置两个客户端变量。

search-mcp-login logout codex 或 logout antigravity 会删除存储的 令牌。要撤销 Antigravity 本身的访问权限，请在 Google 账户的“第三方应用 和服务”中移除它。

无法正常工作时

错误提示	处理方法
codex not configured / antigravity not configured	此机器上没有存储登录信息；请按上述步骤登录
port 1455 and 1457 … are in use，或端口 51121 被占用	另一个登录流程（codex login 或已打开的登录页面）占用了端口；请将其关闭后重试
已达到使用限制、配额或速率限制	等待错误提示中的重置时间；无需密钥的引擎仍可使用
needs Antigravity's OAuth client	安装 Antigravity，或设置两个客户端变量
antigravity 返回 HTTP 403 no valid license	将 SEARCH_MCP_ANTIGRAVITY_VERSION 设为已安装的 Antigravity 版本；这也可能表示 Google 限制了该账户
has expired or was revoked	请重新登录

可选：使用你自己的 API 密钥

你不需要 API 密钥，Agent 也绝不应向你索要。只有在调用指定引擎且操作者已设置自己的密钥时，以下六个引擎才会运行：

引擎	提供商	密钥
brave_api	Brave Search API	SEARCH_MCP_BRAVE_API_KEY
serper	Serper	SEARCH_MCP_SERPER_API_KEY
serpbase	SerpBase	SEARCH_MCP_SERPBASE_API_KEY
tavily	Tavily	SEARCH_MCP_TAVILY_API_KEY
google_cse	Google Custom Search	SEARCH_MCP_GOOGLE_CSE_API_KEY + SEARCH_MCP_GOOGLE_CSE_CX
github_code	GitHub	SEARCH_MCP_GITHUB_TOKEN

将密钥设为环境变量或写入 .env 文件，也可以在本地设置页面中设置：

uv run search-mcp-admin        # local settings / 本地设置 — http://127.0.0.1:8765

（插件或 uvx 安装方式可运行 uvx --from free-search-mcp search-mcp-admin。） 该页面支持双语（中英双语），仅绑定到 127.0.0.1，保存密钥后无需重启即可生效，并且不会再次显示已存储的值。各提供商的操作指南见 docs/API_KEYS.md。

委派查询

委派查询可将页面文本排除在调用方的上下文之外，并返回附有日期的简短答案。默认情况下，这些功能均未启用：

你的需求	使用方式	所需条件
让 Agent 自行搜索和阅读	已安装的工具	无
让主机自己的子 Agent 执行查询	quick-search Agent 定义	支持子 Agent 的主机
让服务通过 Claude Code 分派	SEARCH_MCP_AGENT_BACKEND=claude-code	已登录的 claude CLI
让服务通过 Codex 分派	SEARCH_MCP_AGENT_BACKEND=codex	已登录的 codex CLI
让服务调用你选择的模型端点	SEARCH_MCP_AGENT_BACKEND=api	兼容 OpenAI 或 Anthropic 的 URL
让你自己的代码提供模型	Python 中的 ask(question, answer_with=...)	无其他要求

设置、Agent 文件和实测耗时见 docs/DELEGATION.md。

配置

无需进行任何配置。设置项为 SEARCH_MCP_* 变量，读取顺序为：先读取环境变量，再读取 ./.env，最后读取 ~/.config/search-mcp/.env（SEARCH_MCP_CONFIG_DIR 可更改该目录）。以下是最常修改的设置：

变量	默认值	含义
SEARCH_MCP_PROXY	empty	用于引擎、浏览器和 fetch 的出站代理（http、https 或 socks5）
SEARCH_MCP_PROXY_ENGINES	empty	仅对这些引擎使用代理
SEARCH_MCP_DEFAULT_ENGINES	["duckduckgo","bing","anysearch","mojeek"]	未指定引擎时搜索所用的引擎池
SEARCH_MCP_REGION	us-en	需要区域设置的引擎所用的区域设置
SEARCH_MCP_CACHE_DIR	~/.cache/search-mcp	搜索和页面缓存
SEARCH_MCP_TOOLS	empty	仅注册这些工具

所有设置项均列于 docs/CONFIGURATION.md，并在 .env.example 中说明。

开发

git clone https://github.com/sweetcornna/free-search-mcp.git && cd free-search-mcp
uv sync && uv run playwright install chromium
uv run pytest -q                              # offline
SEARCH_MCP_TEST_NETWORK=1 uv run pytest -v    # live, hits the real web

在检出目录中运行 claude 会加载仓库的 .mcp.json，并启动工作树中的服务。架构说明见 docs/HOW_IT_WORKS.md，发布流程见 docs/RELEASING.md。

致谢

本项目基于以下项目构建：

• mrkrsl/web-search-mcp：httpx 后接 Playwright 的抓取策略，以及多搜索引擎回退链
• Aas-ee/open-webSearch： 多搜索引擎覆盖（Bing/DDG/Baidu/Brave/Startpage）
• VincentKaufmann/noapi-google-search-mcp： 反检测模式（navigator.webdriver、UA、Cookie）、SQLite FTS5 缓存思路，以及多格式 read_document
• nickclyde/duckduckgo-mcp-server： 按搜索引擎限速，以及适合大模型的内容清理
• Mojeek，一个不会根据 User-Agent 设置访问门槛的独立搜索索引
• Model Context Protocol 和 官方 Python SDK

许可证

MIT。请参阅 LICENSE。