使用说明

项目简介

Web Search MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，旨在为 LLM 客户端提供网页搜索和内容浏览功能。它集成了 Google Custom Search API 和网页抓取技术，并具备高级反爬虫机制，确保稳定可靠的服务。

主要功能点

Google Custom Search: 利用 Google Custom Search API 进行网页搜索，支持关键词、可信域名/排除域名、结果数量、安全搜索、日期限制等高级搜索选项。
网页内容浏览: 抓取并解析网页内容，提取包括Markdown格式文本、图片、视频和页面元数据，方便 LLM 理解和处理网页信息。
反爬虫机制: 采用 rebrowser-puppeteer 技术，集成多种反 bot 检测规避策略，例如：运行时泄漏预防、源 URL 伪装、通用工具世界名称和优化的浏览器启动配置，以提高在各种网站上的稳定性和数据获取成功率。
速率限制和缓存: 内置速率限制和缓存机制，防止滥用并提高响应速度，保证服务稳定可靠。
灵活配置: 支持 Cookie 设置、日志配置、浏览器池大小调整等多种配置选项，以满足不同场景的需求。

安装步骤

安装 Bun 运行时: 确保已安装 Bun 运行时 v1.0 或更高版本。
下载仓库代码: 将 GitHub 仓库代码克隆到本地。
安装依赖: 在仓库根目录下运行命令 'bun install' 安装项目依赖。
构建项目: 运行命令 'bun run build' 构建 TypeScript 项目。
配置环境变量:
- 必须设置 'GOOGLE_API_KEY' 和 'GOOGLE_SEARCH_ENGINE_ID' 环境变量，用于 Google Custom Search API 认证。请在 Google Cloud Console 获取 API 密钥和搜索引擎 ID。
- 可选配置其他环境变量，例如 'MAX_CONCURRENT_BROWSERS', 'RATE_LIMIT_WINDOW', 'SEARCH_CACHE_TTL' 等，以调整服务器性能和行为。详细环境变量配置请参考仓库 'README.md' 文档。
配置 Cookie (可选): 如果需要访问需要登录认证的网站，请按照 'README.md' 文档中的 Cookie 设置步骤进行配置。

服务器配置

为了使 MCP 客户端 (如 Claude Desktop, Cline) 能够连接到 Web Search MCP Server，您需要在 MCP 客户端的配置文件中添加服务器配置信息。以下是配置示例，请根据您的实际情况修改路径和 API 密钥等信息。

{
  "mcpServers": {
    "web-search": {  //  服务器名称，在客户端中用于标识和选择服务器
      "command": "bun",  //  启动服务器的命令，这里使用 bun 运行时
      "args": [  //  命令参数
        "run",   //  bun run 命令参数
        "/ABSOLUTE/PATH/TO/web_search_mcp/dist/index.js"  //  MCP 服务器入口文件绝对路径，请替换为实际路径
      ],
      "env": {  //  环境变量配置
        "GOOGLE_API_KEY": "your_api_key",  //  您的 Google API 密钥，**必填**，请替换为您的实际 API 密钥
        "GOOGLE_SEARCH_ENGINE_ID": "your_search_engine_id"  //  您的 Google Search Engine ID，**必填**，请替换为您的实际搜索引擎 ID
        //  其他可选环境变量，可以根据需要进行配置，例如：
        // "MAX_CONCURRENT_BROWSERS": "3",
        // "RATE_LIMIT_WINDOW": "60000"
      }
    }
  }
}

注意:

请将 '/ABSOLUTE/PATH/TO/web_search_mcp/dist/index.js' 替换为服务器 'dist/index.js' 文件的实际绝对路径。
请将 'your_api_key' 和 'your_search_engine_id' 替换为您自己的 Google API 密钥和搜索引擎 ID。
'env' 中的其他环境变量是可选的，您可以根据需要进行配置。

基本使用方法

启动服务器: 在仓库根目录下运行命令 'bun run dev' (开发模式，带watch) 或 'bun run start' (生产模式) 启动 Web Search MCP Server。
配置客户端: 打开您的 MCP 客户端 (如 Claude Desktop, Cline)，根据上述 “服务器配置” 部分，将服务器配置信息添加到客户端的配置文件中。
连接服务器: 重启 MCP 客户端，客户端应该能够自动检测并连接到 Web Search MCP Server。您可以在客户端的工具列表中看到 'search' 和 'view_url' 工具，表示服务器连接成功。
使用工具: 在客户端中，您可以使用 'search' 工具进行 Google 网页搜索，使用 'view_url' 工具浏览并提取网页内容。具体工具参数和使用方法请参考仓库 'README.md' 文档或工具的参数描述。

关键词