配置指南

全部行为都由环境变量控制，共 19 个，且都有合理默认值 —— 因此「不配置」本身就是一个可用的配置。

配置写在哪里

最常见的方式是写在客户端的 mcpServers 配置里，由客户端在拉起进程时注入：

{
  "mcpServers": {
    "ai-search-mcp": {
      "command": "npx",
      "args": ["-y", "ai-search-mcp"],
      "env": {
        "SEARCH_REGION": "cn-zh",
        "SEARCH_LOG_LEVEL": "info"
      }
    }
  }
}

从终端直接运行或自己管理进程时，用 shell 环境变量即可：

SEARCH_REGION=cn-zh SEARCH_LOG_LEVEL=debug npx -y ai-search-mcp

变量速查

引擎选择

SEARCH_ENGINEauto

单个引擎名或逗号分隔的引擎链（如 brave,tavily）。auto 表示按 region 自动选择。

SEARCH_REGION—

区域默认值（如 cn-zh）。既是 search 的默认 region，也决定引擎链走国内还是海外。

SEARCH_MAX_RESULTS10

默认返回条数，取值 1–20。

SEARCH_LANG_ROUTING0

1 = 中文查询优先原生中文引擎（baidu → sogou → so360）。建议仅在大陆住宅 IP 环境开启。

缓存

SEARCH_CACHE_TTL600

缓存 TTL（秒）。0 表示完全关闭缓存。

SEARCH_CACHE_FILE—

缓存持久化文件路径（如 ./.cache/search.json）。设置后重启不丢缓存，仅限单进程使用。

网络与限频

SEARCH_TIMEOUT_MS10000

单次请求超时（毫秒）。

SEARCH_RATE_PER_MINUTE8

每个引擎每分钟最大请求数。0 关闭限频。

SEARCH_MIN_DELAY_MS500

请求间随机延迟下限（毫秒）。0 关闭延迟。

SEARCH_MAX_DELAY_MS2000

请求间随机延迟上限（毫秒）。

SEARCH_HTTP_PROXY—

代理地址（如 http://127.0.0.1:7890）。未设置时回退到 HTTPS_PROXY / HTTP_PROXY。

SEARCH_USER_AGENT内置

自定义 User-Agent。默认使用内置的礼貌爬虫 UA。

抓取

FETCH_MAX_LENGTH8000

fetch_page / research 单页 Markdown 的字符上限。

日志与可观测性

SEARCH_LOG_LEVELinfo

debug | info | warn | error | off。日志输出到 stderr，不污染 MCP 协议流。

SEARCH_LOG_QUERY1

0 = 日志中打码查询词，用于隐私场景。

解析规则覆盖

SEARCH_SELECTOR_FILE—

本地解析规则覆盖文件（JSON）路径。

SEARCH_SELECTOR_OVERRIDE_URL—

远程解析规则覆盖 URL（如 GitHub Gist），启动时拉取，优先级最高。

付费引擎

BRAVE_API_KEY—

使用 brave 引擎时必需。

TAVILY_API_KEY—

使用 tavily 引擎时必需。

场景化配置

中国大陆 · 最简配置

{
  "env": {
    "SEARCH_REGION": "cn-zh"
  }
}

引擎链自动变为 bing → so360 → baidu → sogou，全部直连可用，无需代理。

中国大陆 · 中文效果优先

{
  "env": {
    "SEARCH_REGION": "cn-zh",
    "SEARCH_LANG_ROUTING": "1"
  }
}

中文查询会优先走原生中文引擎。仅在大陆住宅 IP 且百度 / 搜狗可达时才有正收益。

海外部署

{
  "env": {
    "SEARCH_ENGINE": "auto"
  }
}

不设置 SEARCH_REGION，默认链为 google → bing → duckduckgo → yandex。

质量优先（付费引擎在前，免费兜底）

{
  "env": {
    "SEARCH_ENGINE": "brave,tavily,bing",
    "BRAVE_API_KEY": "your-key",
    "TAVILY_API_KEY": "your-key"
  }
}

墙内需要 DDG / Brave / Tavily

{
  "env": {
    "SEARCH_ENGINE": "duckduckgo",
    "SEARCH_HTTP_PROXY": "http://127.0.0.1:7890"
  }
}

缓存持久化 + 详细日志

{
  "env": {
    "SEARCH_REGION": "cn-zh",
    "SEARCH_CACHE_FILE": "./.cache/search.json",
    "SEARCH_LOG_LEVEL": "debug"
  }
}

降低被风控的概率

{
  "env": {
    "SEARCH_RATE_PER_MINUTE": "4",
    "SEARCH_MIN_DELAY_MS": "1200",
    "SEARCH_MAX_DELAY_MS": "3600"
  }
}

把请求速率压到更保守的水平。被 403 或验证码拦截时，正确的应对是降频或换引擎。

日志格式

设置 SEARCH_LOG_LEVEL=debug 后，stderr 会输出结构化的调用记录：

[ai-search-mcp] [info] ready (version 0.4.1, engine=auto, region=cn-zh, logLevel=debug)
[ai-search-mcp] [info] rewrite q="2026年 大模型 最新进展" -> q="大模型 最新进展" +freshness=year
[ai-search-mcp] [info] search q="大模型 最新进展" engine=bing cached=false took=972ms total=3 deduped=1
[ai-search-mcp] [info] fetch url=https://example.com/ len=130 mode=summary took=1189ms
[ai-search-mcp] [debug] engine-fail engine=baidu err=RATE_LIMITED took=1203ms
[ai-search-mcp] [warn] fetch-fail url=https://baike.baidu.com/... err=ENGINE_ERROR took=512ms
不要把日志混进 stdout 服务器使用 stdio 传输，stdout 是 JSON-RPC 协议通道。 因此所有日志都写到 stderr —— 自己包装或重定向输出时请保持这一点，否则会破坏与客户端的通信。

解析规则覆盖的写法

覆盖文件按引擎 key 合并，未提到的引擎继续使用内置规则。以 bing 为例： 

{
  "bing": {
    "challenge": ["captcha", "challenge"],
    "fields": {
      "title": {
        "pattern": "<h2[^>]*>\\s*<a[^>]+href=\"([^\"]+)\"[^>]*>([\\s\\S]*?)<\\/a>\\s*<\\/h2>",
        "flags": "gi",
        "urlGroup": 1,
        "textGroup": 2
      },
      "snippet": {
        "window": "after",
        "size": 2000,
        "pattern": "<p[^>]*>([\\s\\S]*?)<\\/p>",
        "flags": "i",
        "group": 1
      }
    }
  }
}

字段含义

  • title必填。urlGroup 指定 URL 捕获组，textGroup 指定标题捕获组。
  • url可选。window: "before" 表示在标题之前的窗口里找链接。
  • snippet可选。window: "after" 在标题之后找摘要；groups 支持多个捕获组，取首个非空值。
  • snippetAlt可选，摘要的备用规则。
  • challenge反爬检测子串列表，命中即判定为被拦截。
  • domain.fallbackURL 解析失败时的兜底域名。

免发版修复流程：用户反馈「某引擎搜不出来了」→ 维护者把修好的规则更新到一个 Gist → 用户设置 SEARCH_SELECTOR_OVERRIDE_URL=<gist 地址> 重启即修复。

优先级从低到高：内置规则 → 本地文件 → 远程 URL。覆盖加载失败永远不会阻塞启动，只会回退并告警。

关于「什么都没配置」

所有变量都有默认值，因此不写任何配置也能工作：引擎链按 auto 解析， 缓存 10 分钟、限频 8 次/分、超时 10 秒、单页 8000 字符、日志级别 info。 建议的第一步配置只有一条 —— 中国大陆用户加上 SEARCH_REGION=cn-zh。

已复制到剪贴板