Local Web Search MCP Server

面向网页搜索和内容获取的离线优先 MCP 服务器。它不需要外部 API 密钥，并使用本地模型进行意图分类、可选的跨语言搜索、语义重排序和抽取式深度搜索答案。

功能特性

• 浏览器上下文池化，使用持久化的 Playwright 浏览器实例。

• 通过可配置的提供商进行网页搜索，支持健康跟踪和有序回退。

• 可选的跨所有已配置提供商的联合搜索，支持 URL 规范化、跨提供商去重和倒数排名融合（RRF）。

• 可选择加入的意图感知搜索路由，采用保守启发式规则、本地分类器回退和带版本号的提供商配置文件。

• 针对特定站点查询的按域名过滤的网页搜索。

• HTTP 优先的页面获取，包含 GitHub Raw 和 RSS 快速路径，以及针对渲染页面的 Playwright 回退。

• 通过阻止 localhost 和私有网络目标，为 fetch_content 提供 SSRF 保护。

• 针对搜索和获取工具的令牌桶速率限制。

• 由 SQLite 和 sqlite-vec 支持的语义缓存。

• 使用本地 Transformers.js 模型的可选跨语言查询扩展。

• 通过 Readability、JSDOM 和 Turndown 实现的干净 Markdown 提取。

Related MCP server: searxng-mcp

环境要求

• Node.js 20.9.0 或更高版本。

• npm。

• 安装期间需要网络访问，以获取 npm 包、Playwright Chromium 和首次运行的模型下载。

安装

npm install
npm run build

postinstall 脚本会下载 Playwright Chromium。首次使用基于模型的功能时，Transformers.js 会将所需的模型文件下载到本地 Hugging Face 缓存中。首次加载模型的请求可能较慢；后续请求会复用本地缓存。如需最轻量的首次运行，请保持 ENABLE_CROSSLINGUAL=false。明显的 strategy=auto 意图可通过启发式规则解析，无需加载意图分类器；模糊的 auto 查询可能会触发首次运行时的分类器下载。

MCP 客户端配置

将构建好的服务器添加到你的 MCP 客户端配置中：

{
  "mcpServers": {
    "websearch": {
      "command": "node",
      "args": ["path/to/local-websearch-mcp/build/index.js"],
      "env": {
        "RATE_LIMIT_SEARCH_PER_MIN": "10",
        "RATE_LIMIT_FETCH_PER_MIN": "20",
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false",
        "CACHE_DB_PATH": "websearch_cache.db"
      }
    }
  }
}

如果包是全局安装或通过包运行器安装的，请使用二进制入口点：

{
  "mcpServers": {
    "websearch": {
      "command": "local-websearch-mcp",
      "args": [],
      "env": {
        "SEARCH_PROVIDERS": "duckduckgo,bing",
        "ENABLE_CROSSLINGUAL": "false"
      }
    }
  }
}

对于基于包运行器的客户端，一旦包可从配置的 npm 仓库获取，命令可以为 npx，并将 args 设置为 ["-y", "local-websearch-mcp"]。

工具

搜索策略

auto 是特意设计为可选加入的；省略 strategy 时仍会使用 fallback 以保持向后兼容。对于 aggregate 和 auto，语义查询缓存会被绕过，因为查询缓存键尚未按执行策略/提供商计划进行命名空间划分。深度搜索的页面内容继续使用常规内容缓存。

SEARCH_PROVIDERS 既是配置的提供商集合，也是一个白名单。自动路由绝不会激活 SEARCH_PROVIDERS 中未列出的提供商；路由配置文件只改变排序，以及有多少已配置提供商会作为主要候选被选中。

对于聚合型 auto 配置文件，只有当所有选定的主要提供商都未返回可用结果时，才会联系次要的已配置提供商。部分主要提供商成功的结果会被接受，而不会为了增加结果数量而扩大请求范围。这限制了抓取负载，并减少了不必要的封禁/CAPTCHA 暴露。

当前路由配置文件：v1。

这些提供商偏好是初步假设，并非永久性的质量声明。它们带有版本号，因此后续版本可以基于确定性和真实评估证据进行调整，而无需在服务器中散布路由条件逻辑。

意图感知搜索参数示例：

{
  "query": "PostgreSQL connection pooling best practices",
  "strategy": "auto",
  "max_results": 5
}

对于 react.dev 或 github.com 等定向搜索，请使用 domain。意图检测始终接收原始查询；site:<domain> 仅在之后为提供商执行而附加。

{
  "query": "server components reference",
  "domain": "react.dev",
  "strategy": "auto",
  "max_results": 5
}

仅当客户端需要服务器获取排名靠前的页面并从页面文本中提取可能的答案时，才使用 deep=true。MCP 客户端 LLM 仍负责最终的推理和总结。

带有检测到较早日期的搜索摘要会包含一条简短的时效性警告，以便客户端谨慎处理过时的来源。

联合搜索参数示例：

{
  "query": "postgres connection pooling strategies",
  "strategy": "aggregate",
  "max_results": 5
}

fetch_content 在打开浏览器之前会使用快速的源特定路径：

• GitHub 仓库、blob、tree 和 raw URL 会尽可能从 raw.githubusercontent.com 读取。

• RSS 或 Atom 订阅 URL，以及常见的博客/新闻订阅路径，会被转换为最近条目的 Markdown 列表。

• 常规 HTML 页面仍使用 HTTP 优先的 Readability 解析，并带有 Playwright 回退。

配置

Docker

npm run docker:build
npm run docker:up

Docker Compose 将 SQLite 缓存存储在挂载于 /app/data 的命名卷中，并将 Hugging Face 模型存储在单独的命名卷中。容器会设置 CACHE_DB_PATH=/app/data/websearch_cache.db。

开发

npm run build
npm run typecheck
npm test
npm run smoke:mcp
npm audit --audit-level=moderate
npm pack --dry-run --json

npm run smoke:mcp 通过 stdio 启动编译后的服务器，验证三种 web_search 策略值（fallback、aggregate、auto），检查 server_status 中的路由诊断信息，并确认 fetch_content 会阻止 localhost。它不执行真实的提供商搜索，从而使 CI 不依赖搜索引擎的 HTML/网络可用性。

确定性的 TR/EN 路由测试固件位于 evals/search-routing/queries.jsonl 中，由常规 Vitest 测试套件执行。它们验证意图覆盖、保守启发式行为、歧义延迟场景以及提供商白名单的强制实施，而无需加载真实的分类器或联系提供商。

故障排除

• 如果安装后启动失败，运行 npx playwright install chromium。

• 如果首次基于模型的请求较慢，请等待 Transformers.js 模型下载完成，然后重试。

• 如果搜索没有返回结果，请更改 SEARCH_PROVIDERS 的顺序/设置，或尝试直接使用 fetch_content URL。

• 如果聚合模式太慢或触发提供商拦截，请使用默认的 fallback 策略。

• 如果 auto 为你的用例选择了过于宽泛的搜索计划，请使用显式的 fallback 或 aggregate；显式策略会绕过自动规划器。

• 如果 Docker 找不到 Chromium，请使用 npm run docker:build 重新构建镜像。

• 如果缓存文件出现在项目根目录中，请将 CACHE_DB_PATH 设置为专用的数据目录。

npm 打包

npm 包仅包含 build/、README.md、LICENSE 和 SECURITY.md。npm pack 通过 prepack 运行 npm run build，因此包中包含的是编译后的 JavaScript，而不是本地规划文件、测试、缓存或仅源码的工件。

安全

有关报告说明和当前依赖审计说明，请参阅 SECURITY.md。

许可证

ISC