让 AI Agent 搜到 Google 真结果：gsearch 的 MCP 接入与合规边界
给 Agent 接一个搜索工具并不难，难的是弄清它搜的是什么索引、返回的是可直接访问的 URL 还是搜索引擎跳转链接，以及遇到验证码时会不会把空结果伪装成成功。gsearch 是一个 MIT 许可的 Python 项目，尝试通过 MCP 把 Google 搜索结果转成结构化数据，适合评估「让 Agent 使用真实网页搜索」这一类方案。它使用 Camoufox 驱动 Firefox，而不是提供 Google 官方 API；这一实现选择也意味着使用者需要先评估服务条款与访问风险。
MCP 返回的不只是链接列表
项目 README 描述的 google_search 工具会返回 Google 结果页中的自然搜索结果及其真实目标 URL，并可能包含 AI Overview、People also ask、相关搜索等字段。结果数据以结构化 JSON 表达；发生验证码或限流时，项目声称会返回带错误类别和重试信息的错误，而不是用空列表造成「搜索成功但没有结果」的错觉。所有网页字符串都应被视为不可信输入，不能因为结果由搜索引擎返回，就直接交给 Agent 当作指令执行。
它适合需要 Google 索引、希望 Agent 获得相关问题线索，或想统一 MCP 搜索接口的本地实验。它不是通用网页抓取器：README 说链接解析会取得结果的目标地址，但不会继续抓取每个目标网页的正文。后续内容提取仍需单独的读取工具。项目也不是 Google 官方产品，使用真实浏览器访问搜索页面，与调用有明确配额和 SLA 的搜索 API 是不同的工程与合规选择。
安装和接入 MCP 客户端
项目要求 Python 3.12 或更高版本。README 给出的快速开始方式如下：
uv tool install gsearch-agent # 或：pipx install gsearch-agent gsearch setup claude mcp add gsearch --scope user -- gsearch-mcp
gsearch setup 会下载浏览器组件（README 估计约 1 GB）并输出 MCP 配置。实际磁盘占用、安装时间及命令可用性会受平台和网络环境影响；首次部署前应给缓存目录预留空间。项目还给出其他 MCP 客户端的配置样例，核心启动命令是 gsearch-mcp。不要把示例中的代理地址原样照抄到生产环境，应通过客户端环境变量或受保护的配置文件注入真实凭据。
如果要配置代理，项目示例使用 GSEARCH_PROXY，并可用 GSEARCH_DATA_LIMIT_MB 设置数据量限制。例如：
claude mcp add gsearch --scope user \ -e GSEARCH_PROXY="proxy.example.net:7000:user:password" \ -e GSEARCH_DATA_LIMIT_MB=1000 -- gsearch-mcp
这只是项目文档展示的变量形式，不代表任意代理服务都接受同一种认证格式。按代理供应商要求填写，并避免把凭据提交到仓库或写入共享终端历史。README 还称无代理时使用本机 IP，并给出每小时最多 20 次搜索的限制；这是项目当前文档的运行说明，不应误读为 Google 对所有用户提供的配额承诺。
把搜索结果当作数据，不当作指令
MCP 让模型能调用工具，却不会自动解决提示注入。搜索摘要、AI Overview 和网页标题都由第三方控制。较稳妥的 Agent 工作流是：先让模型提出搜索意图，再把搜索结果作为引用材料；进一步打开网页后，用独立步骤抽取正文、核验来源与时间，并要求模型区分来源事实和推断。不要允许搜索结果里的文字直接触发 shell 命令、外发请求或凭据读取。
上线前可以用几条固定查询做离线验收：检查正常结果的 URL 是否指向目标站点，结果字段缺失时 Agent 是否能处理；再检查验证码/网络错误是否明确暴露，而非被包装成成功的空列表。若设置了代理，也要确认请求实际经由预期出口，并了解日志是否包含查询内容。搜索历史可能暴露研究主题、客户名称或内部项目，代理与日志保留策略应一并纳入隐私评估。
最重要的限制：条款与可持续性
gsearch 的 README 明确提醒，自动化访问 Google Search 可能违反 Google 服务条款，要求使用者阅读其「Legal and responsible use」说明。即使技术上可以启动，也不代表获得了服务许可。对商业系统、持续高频工作负载或需要稳定结果的产品，应优先评估有明确授权、配额和服务承诺的搜索 API；不要试图通过代理轮换规避访问限制。
项目 README 还称 Google Custom Search API 将于 2027 年 1 月 1 日关闭。这个时间点属于项目作者提供的背景说明，本文不把它当成独立核实的 Google 官方公告；采用前应以 Google 官方产品公告为准。总的来说，gsearch 值得关注的是它把真实浏览器搜索封装为 MCP 工具、并将失败结构化呈现的工程思路，而不是把它视为无条件可用的免费 API。先确认条款许可，再做小规模验证，才是把搜索能力交给 Agent 的合理起点。