v0.4.1 MIT License Node ≥ 18 零配置 · 零构建 7 个免费引擎

给 Agent 装上
会搜索、会调研的能力

ai-search-mcp 是一个专为 Agent 打造的上网搜索 MCP 服务器 —— 开箱即用的免费搜索引擎、区域感知的自动选引擎与故障转移、freshness 时效过滤、内置缓存，以及一次调用完成整轮调研的 research 组合工具。不需要任何 API Key。

3 步接入指南

ai-search-mcp — stdio server


$
[ai-search-mcp] [info] ready (version 0.4.1, engine=auto, region=cn-zh, logLevel=info)
> search(query="2026年 大模型 最新进展", maxResults=5)
[ai-search-mcp] [info] rewrite q="2026年 大模型 最新进展" -> q="大模型 最新进展" +freshness=year
[ai-search-mcp] [info] search q="大模型 最新进展" engine=bing cached=false took=972ms total=5 deduped=1
{ "query": "2026年 大模型 最新进展", "engine": "bing", "total": 5, "deduped": 1, "results": [{ "id": "a1b2c3d4", "title": "...", "domain": "example.com" }] }

9可插拔引擎

4MCP 工具

137单元测试

0必需的 API Key

bing国内直连首选 google海外索引最佳 duckduckgo隐私友好备选 so360国内最稳中文引擎 baidu中文索引强 sogou微信内容覆盖 yandex俄语 / CIS 强项 brave付费官方 API tavily专为 LLM / RAG bing国内直连首选 google海外索引最佳 duckduckgo隐私友好备选 so360国内最稳中文引擎 baidu中文索引强 sogou微信内容覆盖 yandex俄语 / CIS 强项 brave付费官方 API tavily专为 LLM / RAG

Why this one

现有方案都有硬伤，这个填上了空档

搜索是 Agent 最高频的工具，但常见的四种路线各有取舍 —— 要么不能搜，要么要付费，要么脆弱且输出不可用。

方案	能不能搜	要钱吗	关键短板
官方 fetch MCP	不能	免费	只能抓已知 URL，无法发现新页面
Tavily / Brave / Exa MCP	能	付费 Key	质量高，但全部需要付费 API Key，无免费兜底
社区 DuckDuckGo MCP	能	免费	免费但脆弱：单一引擎、无缓存、无重试、输出非结构化
自建爬虫 / 聚合网关	能	运维成本	要自己维护反爬、限频、解析规则与合规边界
ai-search-mcp	能	免费开箱	9 个引擎可插拔 + 区域感知故障转移 + 时效过滤 + 缓存 + 一次调用调研

核心能力

Zero-Config

零配置开箱即用

npx -y ai-search-mcp 直接跑，不需要任何 API Key。中国用户加一行 SEARCH_REGION=cn-zh 即走国内可直连引擎链，免代理。

Failover

区域感知自动选引擎

中国区域走 bing → so360 → baidu → sogou，海外走 google → bing → duckduckgo → yandex；遇到 429 或超时自动故障转移。

One Call

research 组合工具

一次调用 = 搜索 + 并行抓取 Top 页 → 证据简报。消灭 Agent 5~10 次工具往返；单页抓取失败不影响整体返回。

工程细节

Agent 友好的结构化输出

返回 { id, title, url, snippet, domain }，不是原始 HTML。每条结果带稳定 id（URL 的 sha1 前缀），可直接交给 fetch_page 深读，无需自己拼 URL。

时效过滤与中文查询改写

freshness=day|week|month|year 或精确 timeRange 按引擎自动映射；中文「20xx 年」查询自动去年份 + 补偿时间意图。

内置 TTL 缓存

默认 10 分钟缓存削减重复请求；设置 SEARCH_CACHE_FILE 可持久化到磁盘，进程重启不丢缓存。

引擎健康追踪与优雅降级

持续记录每个引擎的成功/失败与冷却截止；RATE_LIMITED 立即冷却，冷却中的引擎被引擎链跳过，不浪费请求。全部失败时返回逐引擎归因快照，区分「引擎挂了」和「IP 被限」。

解析规则外置，免发版修复

9 个引擎的解析规则全部外置为 JSON，可用本地文件或远程 Gist 覆盖。引擎改版时，改一份 JSON 重启即修复，加载失败不阻塞启动。

礼貌爬虫，合规优先

按引擎限频（默认 8 次/分）+ 随机请求间隔；不做验证码绕过、UA 轮换或代理池对抗 —— 只返回摘要与链接，不转载全文。

How it works

一句话提问，三步拿到可用结果

引擎选择、查询改写、故障转移、缓存与去重全部在内部完成 —— 宿主模型只需要调用一次工具。

调用 · 一句提问

Agent 调用 search，只需传入关键词；时效、域名、区域按需附加。

唯一必填参数就是 query
可选 freshness / timeRange
可限定或排除域名（最多各 5 个）

处理 · 引擎链调度

按区域挑选引擎链，逐个尝试，遇限流或超时立即切换；改写、限频、缓存静默完成。

区域感知：国内链 / 海外链
冷却中的引擎直接跳过
TTL 缓存 + 随机请求间隔

输出 · 结构化结果

返回标准 JSON，Agent 直接消费；需要深读时把 id 交给 fetch_page。

稳定 id，无需手拼 URL
URL 归一化去重，标注 deduped
无缝衔接 research 证据简报

MCP 客户端

Claude Desktop / Cursor / Cline / 自研 Agent

搜索引擎链

区域感知排序 + 健康冷却 + 自动故障转移

结构化返回

结果 JSON / 页面 Markdown / 证据简报

JSON-RPC over stdio

search

结构化搜索结果

research

搜索 + 抓页 → 证据简报

fetch_page · status

页面转 Markdown · 引擎健康诊断

内部能力

TTL 缓存

默认 600s，可持久化

限频与延迟

8 次/分 + 500–2000ms 抖动

健康追踪

untested → healthy → cooling

Tools

四个工具，覆盖「搜 — 研 — 读 — 诊」

MCP 内部不依赖任何 LLM，总结交给宿主模型完成 —— 保持零外部依赖、厂商无关。

search

搜索必填 query

搜索网页并返回结构化结果。返回值里的每条结果都带稳定 id，可直接交给 fetch_page 深读，无需自己拼 URL。

参数要点

query 必填；maxResults 取 1–20（默认 10）
site 限定单个域名；includeDomains / excludeDomains 最多各 5 个，结果侧还会再做一次兜底过滤
freshness 取 day|week|month|year；timeRange 用 "YYYY-MM-DD..YYYY-MM-DD" 且优先级更高
region 同时参与引擎自动选择（如 cn-zh / us-en）

调用示例

{
  "query": "2026年 大模型 最新进展",
  "maxResults": 8,
  "freshness": "week",
  "region": "cn-zh"
}

返回示例

{
  "query": "2026年 大模型 最新进展",
  "queryRewritten": "大模型 最新进展",
  "queryYear": 2026,
  "engine": "bing",
  "engineSwitched": false,
  "cached": false,
  "total": 8,
  "deduped": 2,
  "filtered": false,
  "freshnessApplied": true,
  "freshnessAutoInferred": true,
  "timeRange": "2025-08-25..2026-08-25",
  "results": [
    {
      "id": "a1b2c3d4",
      "title": "标题",
      "url": "https://example.com/article",
      "snippet": "摘要文本",
      "domain": "example.com"
    }
  ]
}

research

组合工具默认抓 2 页

代替 Agent 自己「搜索 → 选页 → 抓取 → 总结」的循环：内部跑完搜索后，按域名多样性挑选 Top 页并行抓取，返回一份证据简报。

设计取舍

选页优先「每个域名取排名最高的一条」，避免单站垄断，也避免某个站 403 拖垮整份简报
多页面并行抓取，单页失败只记作 { url, error }，不影响整体结果
extractMode 默认 summary 返回去噪正文（省 token），full 返回整页 Markdown
内部不调用任何 LLM，总结由宿主模型完成

调用示例

{
  "query": "2026 LLM open source models comparison",
  "maxResults": 5,
  "fetchTopN": 2,
  "extractMode": "summary",
  "freshness": "month"
}

返回示例

{
  "query": "2026 LLM open source models comparison",
  "engine": "bing",
  "overview": {
    "total": 5,
    "deduped": 1,
    "results": [
      { "id": "a1b2c3d4", "title": "...", "url": "...", "snippet": "...", "domain": "..." }
    ]
  },
  "pages": [
    {
      "id": "a1b2c3d4",
      "url": "https://example.com/a",
      "rank": 1,
      "title": "页面标题",
      "headings": [ { "level": 1, "text": "..." } ],
      "content": "去噪后的正文……",
      "length": 4000,
      "truncated": false
    },
    { "id": "e5f6a7b8", "url": "https://other.com/b", "rank": 3, "error": "HTTP 403" }
  ],
  "note": "Evidence brief ready. Summarize based on the page contents and cite source URLs."
}

fetch_page

读取 url 或 id

把任意 URL（或搜索结果里的 id）转成可读内容。返回的 headings 是页面标题大纲，Agent 可以先看结构再决定是否深读。

extractMode：summary 返回去噪正文 mainText（内容优先取 <article> / <main>）；full 返回整页 markdown
maxLength 控制单页字符上限（默认受 FETCH_MAX_LENGTH 约束，8000）
返回 { url, title, description, headings, mainText, markdown, length, truncated, cached }

调用示例

{
  "id": "a1b2c3d4",
  "extractMode": "summary",
  "maxLength": 8000
}

status

诊断零网络请求

搜索失败时用它看为什么：是全部引擎挂掉、某个引擎被限频，还是自己的 IP 被临时限制。只读、不联网、无参数。

引擎状态机

untested 从未使用 → healthy 正常 → degraded 连续失败 → cooling 冷却中（引擎链会跳过）
RATE_LIMITED 立即冷却（按 retryAfter，默认 60s）；其他失败连续 2 次进入冷却
还返回缓存命中统计、运行时长与有效配置

返回示例

{
  "server": "ai-search-mcp",
  "uptimeSec": 1234,
  "config": {
    "engine": "auto",
    "region": "cn-zh",
    "ratePerMinute": 8,
    "cacheTtlMs": 600000,
    "langRouting": false,
    "selectorOverride": false
  },
  "cache": { "size": 12, "hits": 34, "misses": 5 },
  "engines": [
    {
      "engine": "bing",
      "status": "cooling",
      "lastCode": "RATE_LIMITED",
      "consecutiveFailures": 3,
      "cooldownUntil": "2026-08-26T05:06:00.000Z"
    },
    { "engine": "so360", "status": "healthy", "lastCode": null, "consecutiveFailures": 0 }
  ]
}

Engines

九个引擎，按区域自动编排

7 个免费引擎开箱即用，2 个付费官方 API 可按需接入。支持逗号分隔引擎链（如 brave,tavily），任一失败自动转移。

引擎	免费	API Key	时效过滤	适用区域	说明
google	免费	—	不支持	海外专用	索引质量全球最佳；反爬严格，需海外 IP 与会话 Cookie
bing	免费	—	qft	全球	中国区域默认首选；中英文覆盖好，国内免代理直连
duckduckgo / ddg	免费	—	df	全球备选	海外默认链成员；中国大陆直连通常需要代理
yandex / ya	免费	—	不支持	海外专用	俄语 / CIS 内容覆盖强，部分网络可达性好，反爬中等
so360 / 360 / haosou	免费	—	不支持	国内直连	数据中心 / 国内 IP 均可直连，反爬相对宽松；国内链中最稳的中文原生引擎
baidu	免费	—	不支持	仅限国内	中文索引强，但反爬严格；数据中心 IP 下即使带播种 Cookie 仍会触发图形验证码
sogou	免费	—	不支持	仅限国内	微信内容覆盖好；缺少 JS 生成的 SNUID 会话会被 302 拦回
brave	付费	需要	freshness	官方 API	索引质量高，有免费额度；需 `BRAVE_API_KEY`
tavily	付费	需要	time_range	官方 API	专为 LLM / RAG 检索设计；需 `TAVILY_API_KEY`

中国大陆免代理 SEARCH_ENGINE=auto + SEARCH_REGION=cn-zh → bing → so360 → baidu → sogou，全部直连可用，无需额外配置。

海外部署不设置 SEARCH_REGION → 默认链 google → bing → duckduckgo → yandex。Google 质量最优、Bing 最稳，任一失败自动转移。

Configuration

全部行为都由环境变量控制

19 个变量，全部有合理默认值。下面的常用项改一个就生效，完整清单见配置指南。

SEARCH_ENGINEauto

单引擎或逗号分隔引擎链（brave,tavily）；auto 表示按区域自动选择

SEARCH_REGION—

区域默认值，如 cn-zh；同时参与引擎链选择

SEARCH_CACHE_TTL600

缓存 TTL（秒），0 表示关闭缓存

SEARCH_TIMEOUT_MS10000

单次请求超时（毫秒）

SEARCH_RATE_PER_MINUTE8

每个引擎每分钟请求上限，0 关闭限频

FETCH_MAX_LENGTH8000

单页返回 Markdown 的字符上限

SEARCH_CACHE_FILE—

缓存持久化路径，设置后重启不丢缓存

SEARCH_LOG_LEVELinfo

debug|info|warn|error|off，日志写入 stderr 不污染协议流

查看全部 19 个变量

给 Agent 装上会搜索的大脑

零配置、免费、开箱即用。一条命令就能跑起来，三行 JSON 就能接进你的客户端。

阅读快速开始 npm

给 Agent 装上会搜索、会调研 的能力

现有方案都有硬伤，这个填上了空档

零配置开箱即用

区域感知自动选引擎

research 组合工具

Agent 友好的结构化输出

时效过滤与中文查询改写

内置 TTL 缓存

引擎健康追踪与优雅降级

解析规则外置，免发版修复

礼貌爬虫，合规优先

一句话提问，三步拿到可用结果

调用 · 一句提问

处理 · 引擎链调度

输出 · 结构化结果

MCP 客户端

搜索引擎链

结构化返回

search

research

fetch_page · status

TTL 缓存

限频与延迟

健康追踪

四个工具，覆盖「搜 — 研 — 读 — 诊」

search

research

fetch_page

status

九个引擎，按区域自动编排

全部行为都由环境变量控制

给 Agent 装上会搜索的大脑

给 Agent 装上
会搜索、会调研的能力