用于本地大模型的网页搜索 MCP 服务器

一个基于 TypeScript 的 MCP（模型上下文协议）服务器，通过直接连接（无需 API 密钥）多种工具，为不同用例提供全面的网页搜索功能。

特性

• 多引擎网页搜索：优先使用必应 > 布拉夫 > 鸭鸭搜，以确保最佳的可靠性和性能
• 完整页面内容提取：从搜索结果中获取并提取完整的页面内容
• 多种搜索工具：三种专门的工具，适用于不同的应用场景
• 智能请求策略：在 Playwright 浏览器和快速的 Axios 请求之间切换，以确保返回结果
• 并发处理：同时从多个页面提取内容

工作原理

该服务器提供三种专门的工具，以满足不同的网页搜索需求：

1. full-web-search（主工具）

当请求全面搜索时，服务器会使用优化的搜索策略：

1. 基于浏览器的必应搜索 - 使用专用的 Chromium 实例作为主要方法
2. 基于浏览器的布拉夫搜索 - 使用专用的 Firefox 实例作为次要选项
3. Axios 鸭鸭搜 - 最后使用传统的 HTTP 请求作为备用
4. 专用浏览器隔离：每个搜索引擎都有自己的浏览器实例，并自动清理
5. 内容提取：首先尝试 Axios，然后回退到模拟人类行为的浏览器
6. 并发处理：同时从多个页面提取内容，并设置超时保护
7. HTTP/2 错误恢复：当出现协议错误时，自动回退到 HTTP/1.1

2. get-web-search-summaries（轻量级替代工具）

对于不需要完整内容提取的快速搜索结果：

1. 执行与 full-web-search 相同的优化多引擎搜索
2. 只返回搜索结果摘要/描述
3. 不会跟随链接提取完整页面内容

3. get-single-web-page-content（实用工具）

用于从特定网页提取内容：

1. 接受单个 URL 作为输入
2. 跟随该 URL 并提取主要页面内容
3. 移除导航、广告和其他非内容元素

兼容性

此 MCP 服务器已针对 LM Studio 和 LibreChat 进行开发和测试。尚未在其他 MCP 客户端上进行测试。

模型兼容性

重要提示：优先使用专为工具调用设计的较新模型。

较旧的模型（即使指定了工具调用功能）可能无法正常工作或表现不稳定。这似乎在 Llama 和 Deepseek 上尤为明显。目前，Qwen3 和 Gemma 3 表现最佳。

• ✅ 与 Qwen3 兼容良好
• ✅ 与 Gemma 3 兼容良好
• ✅ 与 Llama 3.2 兼容
• ✅ 与近期的 Llama 3.1（如 3.1 swallow-8B）兼容
• ✅ 与近期的 Deepseek R1（如 0528 版本）兼容
• ⚠️ 部分版本的 Llama 和 Deepseek R1 可能存在问题
• ❌ 较旧版本的 Llama 和 Deepseek R1 可能不兼容

安装（推荐）

要求：

• Node.js 18.0.0 或更高版本
• npm 8.0.0 或更高版本

1. 从 Releases 页面 下载最新发布的压缩包

2. 将压缩包解压到系统中的某个位置（例如 ~/mcp-servers/web-search-mcp/）

3. 在解压后的文件夹中打开终端并运行以下命令：

   npm install
   npx playwright install
   npm run build
   

   这将创建包含所有必要依赖项的 node_modules 文件夹，安装 Playwright 浏览器，并构建项目。

   注意：必须在解压后的根目录下运行 npm install，而不是在 dist/ 目录下。

4. 配置你的 mcp.json 文件，使其指向解压后的 dist/index.js 文件：

{
  "mcpServers": {
    "web-search": {
      "command": "node",
      "args": ["/path/to/extracted/web-search-mcp/dist/index.js"]
    }
  }
}

示例路径：

• macOS/Linux：~/mcp-servers/web-search-mcp/dist/index.js
• Windows：C:\\mcp-servers\\web-search-mcp\\dist\\index.js

在 LibreChat 中，你可以将 MCP 服务器添加到 librechat.yaml 文件中。如果你在 Docker 中运行 LibreChat，则需要先在 docker-compose.override.yml 文件中挂载本地目录。

在 docker-compose.override.yml 中：

services:
  api:
    volumes:
    - type: bind
      source: /path/to/your/mcp/directory
      target: /app/mcp

在 librechat.yaml 中：

mcpServers:
  web-search:
    type: stdio
    command: node
    args:
    - /app/mcp/web-search-mcp/dist/index.js
    serverInstructions: true

故障排除：

• 如果 npm install 失败，请尝试将 Node.js 更新至 18 版本及以上，npm 更新至 8 版本及以上
• 如果 npm run build 失败，请确保已安装最新版本的 Node.js
• 对于较旧的 Node.js 版本，可能需要使用该项目的旧版本
• 内容长度问题：如果因内容长度限制而出现异常行为，可在 mcp.json 的环境变量中设置 "MAX_CONTENT_LENGTH": "10000"，或其他值：

{
  "mcpServers": {
    "web-search": {
      "command": "node",
      "args": ["/path/to/web-search-mcp/dist/index.js"],
      "env": {
        "MAX_CONTENT_LENGTH": "10000",
        "BROWSER_HEADLESS": "true",
        "MAX_BROWSERS": "3",
        "BROWSER_FALLBACK_THRESHOLD": "3"
      }
    }
  }
}

环境变量

该服务器支持多个环境变量进行配置：

• MAX_CONTENT_LENGTH：最大内容长度（默认：500000 字符）
• DEFAULT_TIMEOUT：默认请求超时时间（单位：毫秒，默认：6000 毫秒）
• MAX_BROWSERS：最多可维护的浏览器实例数量（默认：3 个）
• BROWSER_TYPES：要使用的浏览器类型列表，用逗号分隔（默认：chromium,firefox；可选：chromium,firefox,webkit）
• BROWSER_FALLBACK_THRESHOLD：在使用浏览器回退之前，允许的 Axios 失败次数（默认：3 次）

搜索质量和引擎选择

• ENABLE_RELEVANCE_CHECKING：启用或禁用搜索结果质量验证（默认：开启）
• RELEVANCE_THRESHOLD：搜索结果的最低质量分数（0.0-1.0，默认：0.3）
• FORCE_MULTI_ENGINE_SEARCH：尝试所有搜索引擎并返回最佳结果（默认：关闭）
• DEBUG_BROWSER_LIFECYCLE：启用详细的浏览器生命周期日志记录，用于调试（默认：关闭）

故障排除

响应时间过慢

• 优化超时设置：默认超时时间已缩短至 6 秒，并采用并发处理以加快响应速度
• 并发提取：现在可以同时从多个页面提取内容
• 进一步缩短超时时间：将 DEFAULT_TIMEOUT=4000，以获得更快的响应（可能会降低成功率）
• 减少浏览器数量：将 MAX_BROWSERS=1，以减少内存占用

搜索失败

• 检查浏览器安装：运行 npx playwright install 以确保浏览器已正确安装。
• 尝试无头模式：在服务器环境中，请确保设置 BROWSER_HEADLESS=true（默认值）。
• 网络限制：某些网络会阻止浏览器自动化操作，可尝试更换网络或使用 VPN。
• HTTP/2 问题：服务器会自动处理 HTTP/2 协议错误，并回退到 HTTP/1.1。

搜索质量问题

• 启用质量检查：将 ENABLE_RELEVANCE_CHECKING=true 设置为启用状态（默认已启用）。
• 调整质量阈值：将 RELEVANCE_THRESHOLD=0.5 设置为更严格的质量要求。
• 强制多引擎搜索：将 FORCE_MULTI_ENGINE_SEARCH=true 设置为启用状态，以尝试所有搜索引擎并返回最佳结果。

内存使用

• 自动清理：每次操作后都会自动清理浏览器，防止内存泄漏。
• 限制浏览器数量：减少 MAX_BROWSERS 的值（默认值为 3）。
• EventEmitter 警告修复：已修复浏览器未正确关闭导致监听器堆积的问题。

开发环境

git clone https://github.com/mrkrsl/web-search-mcp.git
cd web-search-mcp
npm install
npx playwright install
npm run build

开发流程

npm run dev    # 开发模式，支持热重载
npm run build  # 将 TypeScript 编译为 JavaScript
npm run lint   # 运行 ESLint 进行代码检查
npm run format # 运行 Prettier 进行代码格式化

MCP 工具集

本服务器提供三种专门的工具，以满足不同的网页搜索需求：

1. full-web-search（主工具）

这是功能最全面的网页搜索工具：

1. 接受搜索关键词及可选的结果数量（1–10 条，默认 5 条）。
2. 执行多引擎搜索（优先使用 Bing，其次为 Brave，最后是 DuckDuckGo）。
3. 并发抓取每个搜索结果页面的完整内容。
4. 返回结构化数据，包含搜索结果及提取的内容。
5. 增强可靠性：具备 HTTP/2 错误恢复机制、缩短超时时间，并改进了错误处理。

示例用法：

{
  "name": "full-web-search",
  "arguments": {
    "query": "TypeScript MCP 服务器",
    "limit": 3,
    "includeContent": true
  }
}

2. get-web-search-summaries（轻量级替代方案）

适用于快速获取搜索结果的轻量级工具：

1. 接受搜索关键词及可选的结果数量（1–10 条，默认 5 条）。
2. 执行与 full-web-search 相同的优化多引擎搜索。
3. 仅返回搜索结果摘要或描述（不提取页面内容）。
4. 更加快速高效，适合快速研究场景。

示例用法：

{
  "name": "get-web-search-summaries",
  "arguments": {
    "query": "TypeScript MCP 服务器",
    "limit": 5
  }
}

3. get-single-web-page-content（实用工具）

用于从特定网页中提取内容的实用工具：

1. 接受单个 URL 作为输入。
2. 访问该 URL 并提取主要页面内容。
3. 去除导航栏、广告及其他非内容元素。
4. 适用于从已知网页中获取详细内容。

示例用法：

{
  "name": "get-single-web-page-content",
  "arguments": {
    "url": "https://example.com/article",
    "maxContentLength": 5000
  }
}

独立运行

您也可以直接运行服务器：

# 如果从源码运行
npm start

文档

完整的技术细节请参阅 API.md。

许可证

MIT 许可证——详情请参阅 LICENSE。

反馈

本项目为开源项目，我们非常欢迎您的反馈！如果您遇到任何问题或有改进建议，请：

• 在 GitHub 上提交 Issue
• 提交 Pull Request

web-search-mcp 快速上手指南

web-search-mcp 是一个基于 TypeScript 开发的 MCP（Model Context Protocol）服务器，专为本地大语言模型（Local LLMs）提供强大的网页搜索能力。它无需 API Key，通过直接连接 Bing、Brave 和 DuckDuckGo 等多个搜索引擎，实现全面的网页内容提取与搜索。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Windows, macOS, 或 Linux
• Node.js：版本 18.0.0 或更高
• npm：版本 8.0.0 或更高
• 推荐模型：为了获得最佳工具调用效果，建议使用 Qwen3、Gemma 3 或较新版本的 Llama 3.1/3.2。旧版模型可能无法稳定工作。

国内加速提示：如果 npm install 下载依赖较慢，建议配置国内镜像源：

npm config set registry https://registry.npmmirror.com

安装步骤

1. 下载源码 从 Releases 页面 下载最新版本的 zip 文件，并解压到您的本地目录（例如：~/mcp-servers/web-search-mcp/）。

2. 安装依赖与构建 打开终端进入解压后的根目录，依次执行以下命令。这将安装项目依赖、下载 Playwright 浏览器内核并编译 TypeScript 代码。

   npm install
   npx playwright install
   npm run build
   

   注意：务必在项目根目录执行 npm install，不要在 dist/ 目录下执行。

3. 配置 MCP 客户端 根据您的 MCP 客户端（如 LM Studio 或 LibreChat），修改配置文件以指向构建好的入口文件 dist/index.js。

   通用 mcp.json 配置示例：

   {
     "mcpServers": {
       "web-search": {
         "command": "node",
         "args": ["/path/to/extracted/web-search-mcp/dist/index.js"]
       }
     }
   }
   

   • macOS/Linux 路径示例: ~/mcp-servers/web-search-mcp/dist/index.js
   • Windows 路径示例: C:\\mcp-servers\\web-search-mcp\\dist\\index.js

   LibreChat (Docker) 额外配置： 若使用 Docker 运行 LibreChat，需在 docker-compose.override.yml 中挂载本地目录，并在 librechat.yaml 中指定路径为 /app/mcp/...。

基本使用

安装配置完成后，您可以在支持 MCP 的聊天界面中调用以下三个核心工具。

1. 全面网页搜索 (full-web-search)

用途：执行深度搜索，获取搜索结果并提取完整的网页正文内容。 策略：自动按顺序尝试 Bing -> Brave -> DuckDuckGo，确保高成功率。

调用示例：

{
  "name": "full-web-search",
  "arguments": {
    "query": "TypeScript MCP server 教程",
    "limit": 3,
    "includeContent": true
  }
}

2. 快速获取摘要 (get-web-search-summaries)

用途：仅获取搜索结果的标题和摘要片段，不抓取全文。速度更快，适合快速调研。

调用示例：

{
  "name": "get-web-search-summaries",
  "arguments": {
    "query": "2024 年 AI 发展趋势",
    "limit": 5
  }
}

3. 单页内容提取 (get-single-web-page-content)

用途：已知具体 URL 时，提取该页面的主要文本内容（自动去除广告、导航栏等噪音）。

调用示例：

{
  "name": "get-single-web-page-content",
  "arguments": {
    "url": "https://example.com/article",
    "maxContentLength": 5000
  }
}