基于Playwright与MCP协议的本地化AI搜索工具开发实践

1. 项目概述：一个本地化的AI搜索工具

最近在折腾AI助手和自动化工具时，发现一个痛点：很多AI应用需要实时搜索能力，但依赖付费的搜索引擎API（比如SerpAPI）不仅成本高，还有隐私和调用频率的限制。于是，我花了不少时间研究并实践了一个开源方案：web-agent-master/google-search。这是一个基于Playwright和Node.js构建的工具，核心目标是在本地模拟真实用户行为，绕过搜索引擎的反爬机制，执行Google搜索并提取结果。它最吸引我的地方在于，它不仅能作为命令行工具直接使用，还能作为一个MCP服务器，无缝集成到像Claude这样的AI助手中，为其提供实时的网络搜索能力，整个过程完全免费且可控。

这个工具本质上是一个“本地SERP API替代品”。SERP是搜索引擎结果页面的缩写，市面上提供SERP数据抓取的服务通常按月收费。而这个项目让你在自己的机器上就能完成这件事。它通过先进的浏览器自动化技术，智能地管理浏览器指纹、保存和恢复会话状态，甚至能在遇到验证时自动切换到有头模式进行人工干预，极大地提高了在对抗环境下的搜索成功率。对于开发者、研究人员，或者任何需要将网络搜索能力集成到自己应用中的场景，这无疑是一个强大而灵活的基础设施。

2. 核心设计思路与技术选型解析

2.1 为什么选择Playwright作为浏览器自动化核心？

在构建一个需要稳定绕过反爬的搜索工具时，浏览器自动化框架的选择至关重要。市面上主流的选项有Puppeteer、Playwright和Selenium。我最终选择Playwright，是基于以下几个深层次的考量：

首先，跨浏览器支持与现代化API。Playwright由微软开发，原生支持Chromium、Firefox和WebKit三大浏览器引擎。这意味着我们可以针对Google的反爬策略，灵活切换或随机使用不同的浏览器内核，增加行为模式的随机性，降低被单一指纹识别的风险。相比之下，Puppeteer只专注于Chromium，而Selenium的API相对老旧且异步支持不够友好。

其次，强大的自动化与反检测能力。Playwright在设计之初就考虑到了测试场景下的稳定性，它提供了更精准的页面控制、网络拦截、资源模拟等功能。例如，它可以非常方便地注入脚本、修改WebGL指纹、管理WebRTC等，这些都是现代反爬系统用于识别自动化脚本的关键点。项目里提到的“智能浏览器指纹管理”，其底层实现很大程度上依赖于Playwright提供的丰富API。

再者，性能与资源管理。Playwright的浏览器上下文（BrowserContext）机制允许我们在同一个浏览器实例中创建多个完全隔离的会话，每个会话拥有独立的cookie、本地存储和缓存。这对于实现“浏览器状态保存与恢复”功能至关重要。我们可以将一次成功登录或通过验证后的浏览器状态序列化保存下来，下次启动时直接反序列化恢复，避免了每次都要重新经历可能的验证码挑战，显著提升了工具的可用性和效率。

2.2 MCP服务器集成的价值与实现逻辑

Model Context Protocol是Anthropic推出的一套开放协议，旨在让AI助手能够安全、标准化地调用外部工具和数据源。将搜索工具封装成MCP服务器，是该项目的一大亮点，这解决了AI应用生态中的一个关键问题：如何让AI安全、可控地访问实时信息。

传统的做法可能是让AI调用一个自定义的HTTP API，但这需要处理认证、接口定义、错误处理等一系列复杂问题。MCP提供了一套标准的“工具定义、调用、返回”的范式。我们的工具作为MCP服务器启动后，会向Claude Desktop这样的客户端宣告：“我提供了一个名为google_search的工具”。当用户在Claude中提出需要搜索的需求时，Claude会通过MCP协议向我们的服务器发送一个结构化的请求，服务器执行搜索后，再将结构化的结果（JSON格式）返回给Claude，由Claude整合进对话中。

这种设计的优势在于：

1. 安全性：搜索动作发生在用户本地环境，查询关键词和结果不会经过第三方服务器，保护了隐私。
2. 无缝体验：用户感觉像是在直接使用Claude的内置功能，无需在AI和浏览器之间来回切换。
3. 标准化：遵循MCP协议，意味着这个工具理论上可以兼容任何支持MCP的AI客户端，而不仅仅是Claude，增强了其通用性。

实现上，项目使用@modelcontextprotocol/sdk来构建服务器，在mcp-server.ts中定义工具（Tools）和资源（Resources）。当Claude发起搜索请求时，服务器会调用核心的search.ts模块，启动或复用Playwright浏览器实例，完成页面导航、结果提取，最后将格式化后的数据通过MCP协议返回。

2.3 对抗反爬策略的架构设计

这是整个项目的技术核心。现代搜索引擎（尤其是Google）部署了极其复杂的反机器人系统，包括但不限于：行为分析（鼠标移动、点击速度）、指纹识别（Canvas, WebGL, 字体列表）、流量模式检测等。该项目采用了一套组合策略来应对：

策略一：状态持久化与恢复。这是最有效的手段之一。工具在成功执行一次搜索后，可以将整个浏览器上下文的状态（包括cookies、localStorage、sessionStorage甚至IndexedDB）保存到一个JSON文件中（默认是browser-state.json）。下次启动时，直接加载这个状态文件并恢复上下文。这意味着如果你曾经在这个浏览器会话中手动通过了一次验证码，那么恢复后的会话在Google看来依然是那个“已认证的真实用户”，从而大幅降低后续请求被拦截的概率。代码中通过Playwright的browserContext.storageState()和browser.newContext({ storageState: ‘path/to/state.json’ })来实现。

策略二：智能有头/无头模式切换。默认情况下，工具以无头模式运行以提高性能。但无头模式的一些特征容易被检测。项目设计了一个“降级”机制：当检测到搜索失败（例如被重定向到验证码页面）时，工具可以自动切换到有头模式，并暂停执行，将浏览器界面展示给用户。此时，用户可以手动完成验证（如点击“我不是机器人”复选框），验证通过后，工具会保存当前状态，并可能切换回无头模式继续执行后续任务。这个功能在search.ts的错误处理逻辑中体现，通过检测页面URL或特定元素是否存在来判断是否遇到了验证。

策略三：指纹随机化与模拟。虽然项目文档提到此功能，但在代码层面可能需要更深入的定制。Playwright允许在创建浏览器上下文时传入一系列参数来模拟不同的设备，如userAgent、viewport、deviceScaleFactor、isMobile等。一个健壮的实现应该从一份设备列表中随机选择配置，并在每次启动或定期更换，使得每次请求看起来都来自不同的设备。此外，还可以通过page.addInitScript注入JavaScript代码来覆盖或混淆一些通过JS获取的指纹信息，如navigator.plugins,navigator.languages等。

策略四：人性化操作间隔与流量控制。过于规律的请求间隔是机器人的典型特征。工具应该在搜索、点击、滚动等操作之间加入随机的延迟，模拟人类用户的犹豫和阅读时间。同时，必须避免高频请求，这是触发封禁的最直接原因。虽然工具本身没有硬性限制，但在使用说明中明确提示“不要过于频繁地发送请求”，在实际集成到自动化流程时，调用方必须自己实现请求速率限制。

3. 环境搭建与实战部署指南

3.1 从零开始：本地开发环境配置

要运行或二次开发这个项目，你需要一个基础的Node.js开发环境。我推荐使用pnpm作为包管理器，因为它比npm和yarn在磁盘空间和安装速度上更有优势，项目本身也提供了pnpm的脚本。

第一步：获取项目代码。

git clone https://github.com/web-agent-master/google-search.git cd google-search

第二步：安装依赖并构建。这里有一个关键点：Playwright需要下载浏览器二进制文件。这个过程可能会比较慢，并且可能受到网络环境影响。

# 使用pnpm安装项目依赖 pnpm install # 安装Playwright的浏览器（Chromium, Firefox, WebKit）。这一步非常重要，如果失败会导致工具无法启动。 pnpm exec playwright install # 或者，如果只想安装Chromium以节省空间和时间 pnpm exec playwright install chromium # 编译TypeScript源代码到JavaScript pnpm build

注意：pnpm exec playwright install这个命令是Playwright CLI的标准调用方式，它会在后台下载大约几百MB的浏览器文件到系统缓存目录。如果遇到下载超时或失败，可以考虑设置环境变量PLAYWRIGHT_DOWNLOAD_HOST来使用国内镜像源，或者手动从其他途径获取浏览器并放置到正确路径。

第三步：全局链接（针对命令行工具和MCP）。为了让google-search命令在系统的任何地方都能被识别，需要将其链接到全局。

pnpm link --global

执行成功后，你就可以在终端直接输入google-search --help来测试了。如果提示命令未找到，可能是你的系统PATH没有包含pnpm的全局bin目录，通常需要将~/.local/share/pnpm/global/5/node_modules/.bin（Linux/macOS）或%APPDATA%\pnpm\global\node_modules\.bin（Windows）添加到环境变量PATH中。

3.2 Windows环境下的特殊配置与避坑

项目文档特别提到了对Windows的适配，这在实践中非常重要。我在Windows 11上部署时遇到了几个典型问题，以下是解决方案：

问题1：权限与路径分隔符。Windows的CMD和PowerShell对路径和脚本的执行策略与Unix系终端不同。项目提供了.cmd脚本来包装命令。当你运行pnpm build后，在dist目录下会生成.js文件，而bin目录下的入口脚本会调用它们。确保你的命令行终端（建议使用Windows Terminal或VS Code集成终端）有足够的权限运行脚本。

问题2：Playwright浏览器安装失败。在Windows上，首次安装Playwright浏览器可能需要管理员权限，特别是如果它尝试将浏览器安装到受保护的目录。解决方案是：

1. 以管理员身份运行你的终端（CMD或PowerShell）。
2. 然后执行pnpm exec playwright install chromium。
3. 如果依然失败，可以尝试关闭杀毒软件或防火墙的实时保护（临时），因为有些安全软件会拦截浏览器二进制文件的下载和写入。

问题3：MCP服务器配置路径问题。在Claude Desktop配置中指定MCP服务器路径时，Windows的路径格式是个大坑。

{ "mcpServers": { "google-search": { "command": "node", "args": ["C:\\Users\\YourUsername\\projects\\google-search\\dist\\src\\mcp-server.js"] } } }

注意，这里需要使用双反斜杠\\或者正斜杠/。我强烈推荐使用正斜杠，因为Node.js能很好地处理它，且更清晰：“C:/Users/YourUsername/projects/google-search/dist/src/mcp-server.js”。另外，路径中不要包含中文或特殊字符，避免出现不可预知的问题。

问题4：临时文件目录。工具运行时产生的日志和临时文件，在Windows上默认会放在%TEMP%目录下（通常是C:\Users\<用户名>\AppData\Local\Temp）。如果工具报错找不到路径，可以检查该目录是否存在以及是否有写入权限。通常这不是问题，但如果你使用了重定向或特殊的磁盘管理软件，可能需要留意。

3.3 与Claude Desktop的深度集成实战

将搜索工具作为MCP服务器集成到Claude Desktop，是实现AI辅助搜索的关键一步。这个过程比单纯命令行使用要复杂一些，但一旦配置成功，体验是质的飞跃。

第一步：确认Claude Desktop版本。确保你安装的是支持MCP的Claude Desktop版本。较老的版本可能没有此功能。前往Claude官网下载最新版即可。

第二步：定位并编辑配置文件。这是最关键的一步。配置文件的位置因操作系统而异：

• macOS:~/Library/Application Support/Claude/claude_desktop_config.json
• Windows:%APPDATA%\Claude\claude_desktop_config.json。一个快速打开的方法是：在文件资源管理器的地址栏直接输入%APPDATA%\Claude并回车。

如果该文件或目录不存在，你需要先启动一次Claude Desktop，它可能会自动创建。如果还没有，可以手动创建Claude文件夹和其中的claude_desktop_config.json文件。

第三步：编写配置文件。我测试了多种配置方式，最稳定的是使用node命令直接执行编译后的JS文件。假设你的项目克隆在D:\Dev\google-search。

{ "mcpServers": { "google-search": { "command": "node", "args": ["D:/Dev/google-search/dist/src/mcp-server.js"], "env": { "NODE_ENV": "production" } } } }

保存这个JSON文件。注意JSON的格式必须正确，最后一个项后面不能有逗号。

第四步：重启与验证。完全关闭Claude Desktop（包括系统托盘图标），再重新启动。启动时，观察Claude的日志窗口（如果有）或终端（如果你从命令行启动），应该能看到它正在尝试连接MCP服务器的信息。在Claude的对话界面，你可以尝试输入“搜索一下今天的热点新闻”或“find the latest research about LLM”。如果配置成功，Claude会理解你的意图，并在后台调用我们的搜索工具，然后将结果整合到回复中。你可能会看到它思考时显示“使用谷歌搜索中...”之类的提示。

实操心得：配置成功后，第一次使用搜索功能时，Claude可能会提示“需要用户确认使用外部工具”。点击允许即可。之后，Claude会记住这个授权。如果遇到连接失败，首先检查配置文件路径是否正确，其次可以尝试在命令行手动运行node D:/Dev/google-search/dist/src/mcp-server.js，看服务器是否能正常启动并监听（默认是stdio通信，不会有网络端口）。如果手动运行报错，根据错误信息排查Node环境或项目依赖问题。

4. 核心功能使用详解与参数调优

4.1 命令行工具：从基础搜索到高级调试

安装并链接后，命令行工具提供了最直接的控制方式。基础用法非常简单：

google-search “什么是机器学习”

这会使用默认参数（无头模式，超时60秒，返回10条结果）进行搜索，并将JSON格式的结果打印到终端。

但它的强大之处在于丰富的命令行选项，让你能应对各种复杂场景：

控制搜索结果数量与超时：

google-search -l 5 -t 30000 “OpenAI”

-l 5限制只返回最相关的5条结果，这在只需要少量精准信息时非常有用，能加快返回速度。-t 30000将超时时间设置为30秒。对于网络状况不佳或目标网站响应慢的情况，可以适当调高这个值；反之，如果希望快速失败，可以调低。

调试与问题排查：

google-search --no-headless “遇到验证码了”

当你的搜索频繁失败，怀疑是被重定向到验证页面时，使用--no-headless参数。这会打开一个真实的浏览器窗口，让你亲眼看到发生了什么。你可能会看到Google的“我不是机器人”复选框或者图片验证。手动完成验证后，工具可以继续执行（如果脚本支持等待的话），或者至少你能明确问题所在。结合--remote-debugging-port 9222参数，你还可以在Chrome浏览器中打开chrome://inspect来连接这个浏览器实例，使用开发者工具进行更深入的调试。

状态管理：突破反爬的关键。

# 第一次搜索，并保存浏览器状态 google-search --state-file ./my-profile.json “第一次搜索” # 使用保存的状态进行后续搜索（极大可能绕过验证） google-search --state-file ./my-profile.json “后续搜索”

--state-file参数是指定浏览器状态文件的路径。这是本工具提高成功率的核心技巧。我的工作流通常是：先以--no-headless模式运行一次搜索，手动完成所有可能的验证（登录、CAPTCHA等），确保这次搜索成功返回结果。这次运行会自动将状态保存到默认或指定的文件。之后，所有的自动化搜索都使用这个状态文件。这个状态文件包含了cookies、本地存储等，让Google认为后续请求来自同一个“已认证的会话”。请妥善保管这个文件，因为它可能包含你的会话身份信息。

获取原始HTML：应对页面结构变更。

google-search “playwright tutorial” --get-html --save-html --html-output ./search_page.html

--get-html参数让工具返回清理后的HTML源码，而不是解析后的结果。--save-html将其保存为文件，--html-output指定保存路径。这个功能有两个主要用途：

1. 调试解析器：当工具的搜索结果解析突然失效（返回空数组）时，很可能是Google更新了搜索结果页的HTML结构。保存下当时的HTML，可以帮助你分析新的DOM结构，从而更新工具中的CSS选择器或解析逻辑。
2. 深度分析：有时你可能需要的不仅仅是标题、链接和摘要，而是整个页面的特定信息。获取原始HTML后，你可以用自己的解析脚本（如Cheerio、BeautifulSoup）进行更灵活的抽取。

4.2 结果解析与数据利用

工具返回的标准JSON结构非常清晰：

{ “query”: “搜索关键词”, “results”: [ { “title”: “结果标题”, “link”: “https://...”, // 真实的目标URL，而非Google的重定向链接 “snippet”: “结果的文字摘要” } // ... 更多结果 ] }

这个结构很容易被其他程序消费。例如，你可以写一个简单的Node.js脚本，将搜索结果导入数据库，或者过滤掉特定域名的结果。link字段已经处理了Google的跟踪重定向，直接指向目标网站，这省去了额外解析的步骤。

一个实用的管道示例：搜索并提取所有链接。

google-search “node.js best practices 2024” -l 20 | jq -r ‘.results[].link’ > links.txt

这里使用了jq这个强大的命令行JSON处理器，从结果中提取所有链接并保存到文件。然后你可以用wget或curl批量下载这些页面进行分析。

4.3 MCP服务器模式下的交互模式

当工具以MCP服务器模式运行时，交互方式从命令行变成了与AI助手的自然语言对话。这带来了不同的使用哲学和技巧。

在Claude中，你不再需要记忆命令参数。你可以用非常自然的方式提出需求：

• “帮我搜索一下Python异步编程的最新教程。”
• “Find recent academic papers about diffusion models.”
• “查一下北京明天飞上海的航班。”

Claude会理解你的意图，将其转化为对MCP服务器的工具调用。服务器执行搜索后，Claude不仅会列出结果，还会基于它的理解能力对结果进行总结、归纳和提炼。例如，你问“AI领域最近有什么突破？”，Claude可能会调用搜索工具，获取一系列新闻和论文标题，然后整合成一段连贯的概述，指出几个最重要的进展，并附上来源链接。

使用技巧：

1. 明确指令：虽然AI很智能，但明确的指令能得到更好的结果。例如，“搜索三家提供免费SSL证书的机构，并列出它们的优缺点”比单纯“SSL证书”要好。
2. 结果过滤：你可以要求Claude对结果进行过滤，比如“只要最近一个月内的结果”、“只要来自GitHub或Stack Overflow的结果”。
3. 结合上下文：MCP搜索可以无缝融入长对话。你可以先和Claude讨论一个技术问题，当它需要最新信息时，它会自动提议或你直接要求它进行搜索，搜索的结果会完美融入后续的讨论中。

注意事项：MCP服务器是常驻进程（由Claude Desktop管理）。这意味着浏览器实例可能会在后台保持一段时间。虽然有利于状态保持，但也会占用内存。如果长时间不用，可以重启Claude Desktop来释放资源。另外，所有通过Claude进行的搜索，其查询词和结果会作为对话历史的一部分，请注意隐私。

5. 高级技巧、问题排查与二次开发

5.1 提升搜索成功率的实战经验

即使有了状态管理和指纹模拟，在长期、大规模的自动化搜索中，仍然可能触发Google的防御机制。以下是我总结的几条提升稳定性的经验：

1. 使用住宅IP代理池。这是最有效但也是最复杂的手段。数据中心的IP地址（来自AWS、GCP、Azure等）被标记和封禁的概率很高。使用高质量的住宅代理IP可以极大改善这一情况。你可以在创建Playwright浏览器上下文时通过proxy参数设置代理。

// 这是一个概念性示例，实际配置需参考Playwright文档和你的代理服务商 const context = await browser.newContext({ storageState: ‘./state.json’, proxy: { server: ‘http://your-residential-proxy:port’, username: ‘your-username’, password: ‘your-password’ } });

成本考量：可靠的住宅代理价格不菲。你需要权衡项目需求与成本。

2. 模拟更复杂的人类行为模式。除了随机延迟，还可以加入更细粒度的操作：

• 随机滚动：在页面加载后，随机滚动页面几次，模拟阅读行为。
• 鼠标移动轨迹：使用Playwright的page.mouse.move(x, y)模拟非直线的鼠标移动路径。
• 不完美的点击：点击链接或按钮时，不一定精确点击中心，可以加入小幅度的随机偏移。 这些可以通过在页面中注入脚本或使用Playwright的API实现，但会显著增加脚本复杂度和执行时间。

3. 多状态文件轮换。不要只依赖一个状态文件。可以创建多个“身份”（即不同的状态文件），在每次搜索或每N次搜索后轮换使用。这模拟了多个用户交替访问的行为。你需要一个机制来管理这些状态文件的创建、维护和轮换逻辑。

4. 识别并处理验证码页面。尽管工具能自动切换有头模式，但在全自动化流程中，我们希望能检测到验证码并采取策略。可以通过检查页面标题、URL或特定元素（如#captcha-form）是否存在来判断。如果检测到，可以： - 记录日志并跳过当前任务。 - 切换到备用的搜索策略（如使用不同的初始关键词）。 - 触发一个告警，通知人工处理。

5.2 常见错误排查手册

在实际部署和使用中，你可能会遇到以下问题。这里提供一个快速排查指南：

5.3 二次开发：定制化你的搜索工具

这个项目的代码结构清晰，基于TypeScript开发，非常适合进行二次开发以满足特定需求。

修改解析逻辑：如果你需要提取搜索结果中的额外信息，比如显示URL、发布时间、网站图标等，需要修改src/search.ts文件中的parseSearchResults函数。这个函数使用page.$$eval和CSS选择器来定位和提取数据。仔细研究Google搜索结果页的HTML结构，调整选择器即可。

添加新的搜索引擎：虽然项目叫google-search，但其架构可以扩展。你可以复制search.ts的核心逻辑，创建一个新的函数（如bingSearch），修改导航的URL（https://www.bing.com/search?q=...）和对应的结果解析逻辑。然后在index.ts或新的CLI命令中暴露这个功能。

集成到现有Node.js应用：你不一定非要通过命令行或MCP调用。可以将search.ts中的searchGoogle函数作为一个模块导入到你自己的Node.js项目中。

import { searchGoogle } from ‘./path/to/google-search/src/search’; // 或者使用编译后的JS // const { searchGoogle } = require(‘./path/to/google-search/dist/src/search’); async function myApp() { const results = await searchGoogle({ query: ‘你的关键词’, headless: true, limit: 5, stateFilePath: ‘./my-state.json’ }); console.log(results); }

这样，你就可以在后台服务、定时任务或Web API中直接使用搜索功能。

优化性能与资源：默认情况下，每次搜索都可能启动/关闭一个浏览器实例，开销较大。对于高频但间隔短的搜索任务，你可以修改代码，实现一个浏览器实例池。维护一个可复用的浏览器实例和多个上下文，搜索请求从池中获取上下文来执行，完成后归还，而不是完全关闭。这需要更复杂的并发管理和状态隔离，但能极大提升性能。

最后，记住这个工具的核心价值在于其本地化、可定制和免费的特性。它可能不如商业API稳定和省心，但它给了你完全的控制权和数据隐私。在合规使用的前提下，它是连接AI与实时网络信息的一座非常有力的桥梁。