gsearch

快速开始 · 对比情况 · 你能获得什么 · 工作原理 · 代理 · 性能 · 常见问题

为你的 AI Agent 提供真实的 Google 搜索。无需 API 密钥。可自托管。通过 MCP 使用。

你的 Agent 调用 google_search，即可获得 Google 实际的搜索结果页，并以类型化 JSON 格式返回：每个链接都会解析为真实 URL，还包含 Google 的答案框（体育赛事结果、头条新闻、视频）、AI 概览、“其他人还问了”问题和相关搜索。真正的 Firefox (Camoufox) 会原样运行 Google 页面，使用你自己的 IP，或通过你已有的任意代理访问。

**原因：**普通 HTTP 请求会遇到 JavaScript 屏障；在我们的测试中，自动化 Chrome 两次尝试都遇到了 CAPTCHA；而 Google 官方的 Custom Search API 将于 2027 年 1 月 1 日关闭。其他搜索 MCP 服务要么不使用 Google 的索引（Brave、Tavily、Exa、DuckDuckGo），要么按查询次数收费（SerpApi、Bright Data）。

_{在家庭 IP 上通过预热会话进行的真实实时调用，根据录制的结果渲染；图中等待时间为实测时间。MP4}

🚀 快速开始

uv tool install gsearch-agent                         # or: pipx install gsearch-agent
gsearch setup                                         # downloads the browser once (~1 GB), prints your MCP config
claude mcp add gsearch --scope user -- gsearch-mcp    # or any MCP client, below

然后直接提出请求：“在 Google 上搜索 asyncio 是什么，并给我前三个链接”、“人们还会问哪些关于 asyncio 的问题？”、“查找过去一年 python.org 上的 asyncio 页面。”、“搜索 asyncio 文档并总结第一个结果。”

不使用代理时，gsearch 会使用你自己的 IP，每小时最多搜索 20 次。需要更多搜索时，可添加任意格式的代理：

claude mcp add gsearch --scope user -e GSEARCH_PROXY="gate.example.com:7000:user-sid-{sid}:password" -e GSEARCH_DATA_LIMIT_MB=1000 -- gsearch-mcp

{
  "mcpServers": {
    "gsearch": {
      "command": "gsearch-mcp",
      "env": { "GSEARCH_PROXY": "optional, any format", "GSEARCH_DATA_LIMIT_MB": "1000" }
    }
  }
}

说明

自动访问 Google 搜索可能违反 Google 的服务条款。运行实时搜索前，请阅读 合法与负责任的使用。

🆚 对比

_{“视情况而定”：我们未测试这些项目。我们唯一的 Chromium 测量记录是 F-0001：在提供 gsearch 服务的 IP 上，Playwright Chrome 有 2 次中的 2 次遇到了 CAPTCHA。 运行实时搜索前请阅读法律。}

_{测量于 2026 年 10 月： F-0014、 F-0006、 F-0011、 F-0012、 F-0001； 干净代理 IP 上耗时 14 秒、用量 0.6 MB：F-0015。 被标记的代理池速度较慢：参见性能。}

✨ 为什么选择 gsearch

Google 官方搜索 API 不再接受新客户，并将于 2027 年 1 月 1 日关闭 （F-0005）。gsearch 专为 AI Agent 打造：

• 🦊 真正的浏览器，而非爬虫。 Camoufox 是经过强化的 Firefox，会原样运行 Google 页面，使用真实设备指纹，并让地区设置与 IP 相匹配。
• 🔗 真实 URL。 Google 会将结果链接隐藏在 /goto 重定向之后。gsearch 会将每个链接解析为其指向的页面 URL，但不会加载该页面。
• 🤖 专为 Agent 打造。 一个 MCP 服务：搜索、页面读取和状态查询，返回类型化 JSON。拦截会以清晰的错误返回，并附带 retry_after_s，绝不会返回空结果；同时，每个字符串都会标记为不可信的网页内容。
• 🌍 支持任意代理和格式。 轮换住宅代理、静态 VPS 或数据中心代理列表，支持 HTTP、HTTPS 或 SOCKS5，以及任何常见布局。每个字节都会计数，并设有严格的数据用量上限。
• 🎯 无需调优。 只需两个设置。其他设置均固定为测试中效果最佳的值。
• 📊 数据如实呈现。 README 中的每项说法都附有测量方法的详细说明链接。

📦 Agent 能获取的内容

保存的结果页中的实际输出（离线演示模式下，url 保持为 null；实时搜索会填入该字段）：

遇到拦截时，返回的绝不会是空列表，而是会说明发生了什么以及需要等待多久的错误：

🔍 工作原理

• 像真人一样操作。 使用可见窗口，因为通过代理 IP 访问时，无头会话更容易受到质疑 （F-0015）。查询会输入到地址栏中。 WebRTC 已关闭，因此你的 IP 不会绕过代理泄露。
• 绝不伪造。 gsearch 不会生成或篡改 Google 的令牌：浏览器会原样运行页面。
• 低成本解析链接。 在相同 IP 上使用相同 Cookie 解析链接，TLS 指纹与浏览器匹配 （F-0011， F-0013）。
• 可在服务端运行。 在没有屏幕的 Linux 机器上，浏览器会自动使用虚拟显示器 （sudo apt install xvfb）。

🌍 代理

# rotating residential: {sid}, or your provider's sid-…, session-…, sessid-… part, gives a new IP per search
GSEARCH_PROXY=gate.example.com:7000:user-country-us-sid-{sid}:password

# static proxies (VPS, datacenter, ISP): one or many, separated by commas, spaces or new lines
GSEARCH_PROXY=socks5://user:[email protected]:1080, http://203.0.113.11:3128

# or a file with one proxy per line
GSEARCH_PROXY=/path/to/proxies.txt

• 轮换代理： 每次搜索使用新的 IP 和新的浏览器，最多同时执行 3 次。被拦截的 IP 会被替换，每次搜索最多使用 4 个 IP。会检查登录信息中的 country-xx 或 cc-xx，并丢弃位于其他地区的出口 IP。
• 静态代理： 每个 IP 保留一个预热会话，多个 IP 轮流使用。每个 IP 都有独立额度（每小时 20 次搜索， 每天 150 次），遇到 CAPTCHA 后会休息到午夜，因此十个 IP 每小时最多可进行约 200 次搜索。
• 流量： 所有流量都会经过本地中继进行统计；达到设定上限后，GSEARCH_DATA_LIMIT_MB 会停止 所有操作，即使重启后也会继续生效。

提示

请查看代理提供商的可接受使用政策。许多提供商禁止在服务条款不允许自动访问的网站上使用其网络，也禁止破解 CAPTCHA。

📊 性能

代理质量决定速度和成本。 许多住宅 IP 已被 Google 标记。每个被标记的 IP 都会在尝试下一个 IP 之前消耗一次浏览器启动资源（约 0.7–1 MB 和 20 s）。

不使用代理时，在你自己的 IP 上，已预热的会话每次搜索耗时 ~1.2 s，测试中所有链接均已解析，且未遇到 CAPTCHA（F-0014）；为保护你的 IP，每小时最多搜索 20 次。静态代理尚未经过基准测试。

在数据限额内测量你自己的代理：

python tools/benchmark.py -n 10

🛠 参考

gsearch search "query" [--page N] [--lang xx] [--country xx] [--time-range h|d|w|m|y] [--site domain]
gsearch search "query" --fixtures fixtures/gecko     answer from saved pages (offline, from a clone of this repo)
gsearch fetch URL                                    readable text and links of a web page
gsearch parse page.html                              parse any saved Google results page
gsearch schema                                       print the JSON Schema
gsearch identity check                               home-IP browser's fingerprint matches its IP (no Google traffic)
gsearch setup                                        download the browser once and print the MCP config

import asyncio
from gsearch_core.client import SearchClient
from gsearch_core.config import fetcher_from_env
from gsearch_parse.models import SearchRequest

async def main() -> None:
    fetcher, _live = fetcher_from_env()      # reads the settings and .env
    result = await SearchClient(fetcher).search(SearchRequest(query="what is asyncio in python"))
    print(result.model_dump_json(indent=2))  # SearchResponse or SearchError
    await fetcher.aclose()

asyncio.run(main())

我需要代理吗？ 不需要。没有代理时，gsearch 会使用你自己的 IP 和一个预热会话（每次搜索约 1.2 s），并限制为每小时 20 次、每天 150 次搜索，以保持你的 IP 状态良好。需要更高用量时，请使用代理。

应该买哪种代理？ 选择支持粘性会话（用户名中包含会话 ID）的轮换住宅代理。质量比价格更重要：购买更多流量前，先用小套餐运行 tools/benchmark.py。

一次搜索会使用多少代理流量？ 在干净的 IP 上约为 0.6 MB。被标记的 IP 会耗费更多流量，因为每个 IP 都会导致一次无效的浏览器启动。设置 GSEARCH_DATA_LIMIT_MB，就能避免超支。

它能解决 CAPTCHA 吗？ 不能。被封锁的 IP 会被丢弃，并尝试使用一个新的 IP。gsearch 不附带 CAPTCHA 求解器，也绝不会伪造 Google 的令牌。

它能在服务器上运行吗？ 可以。在没有屏幕的 Linux 上，安装 Xvfb 后，浏览器会在虚拟显示器中运行。

哪些 Agent 可以使用它？ 任何 MCP 客户端都可以：Claude Code、Claude Desktop、Cursor 等。你也可以使用 CLI 或从 Python 调用它。

📜 法律与负责任的使用

• Google 的服务条款限制对 Google 搜索的自动访问。 无论本项目的许可证如何规定，使用此工具访问 Google 都可能违反这些条款。
• 诉讼风险真实存在，且当前仍然有效。 在 Google v. SerpApi 案（加州北区，立案日期为 2025-12-19）中，Google 主张，通过自动化方式解决其 SearchGuard JavaScript 挑战属于规避 DMCA §1201。gsearch 会在真实浏览器中运行该挑战，不会伪造或修改令牌，但诉状也将自动化浏览器列为目标。请参阅 docs/DESIGN.md（D-004）。
• 本项目不附带、不集成也不推荐任何 CAPTCHA 求解器。 CAPTCHA 会重置身份，并作为错误报告。
• 在运行实际搜索前，请针对你的司法管辖区和使用场景寻求法律建议。 解析器（gsearch_parse）只会读取你已有的 HTML。
• 默认启用限制，且无法通过 CLI 或 MCP 绕过。 请勿使用代理对 Google 发起高频请求。
• 不得收集个人数据。 请勿对个人进行画像、抓取人物搜索结果或大规模收集个人数据。缓存应设为较短的有效期，也不要重新发布原始结果。
• 遇到封锁时，请暂停请求。 CAPTCHA 和速率限制会作为错误返回，并包含 retry_after_s。gsearch 绝不会试图绕过挑战。

提示词注入

结果中的每个标题、摘要、URL 和问题都是来自开放网络的不可信第三方文本，其中可能包含针对你的 Agent 的指令。工具描述中对此有明确说明，每个响应都会携带 meta.untrusted_content: true 和 MCP untrusted_content 标志，文本摘要末尾也会附带警告。请始终将结果严格视为数据。

🤝 参与贡献

测试绝不会联系 Google：解析器使用保存的页面进行测试，浏览器则使用本地的模拟 Google 进行测试。欢迎提交拉取请求：选择一个 适合新手的议题，查看 路线图，并从 CONTRIBUTING.md 和 docs/DESIGN.md 开始。

如果 gsearch 帮你节省了时间，点个 ⭐ 就能让更多人发现它。

许可证

MIT。Camoufox（MPL-2.0）作为依赖从 PyPI 安装，不会被 vendored。