Skip to content
Back to search

serpmaven

Self-hosted Google search scraper for Python. Scrape Google SERP results with a real Chrome browser and your own residential proxy. Self-hosted SERP API alternative with JSON output, an HTTP API and an MCP server for AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/nodemaven/serpmaven with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/nodemaven/serpmaven'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nodemaven--serpmaven/badge.svg)](/listings/nodemaven--serpmaven)

HTML

<a href="/listings/nodemaven--serpmaven"><img src="/api/listings/nodemaven--serpmaven/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Python 3.10 or newer, in a virtual environment:

python3 -m venv serpmaven-env
source serpmaven-env/bin/activate
pip install serpmaven
patchright install chromium
serpmaven doctor

In PowerShell:

python -m venv serpmaven-env
Set-ExecutionPolicy -Scope Process Bypass -Force   # lets this window run Activate.ps1
.\serpmaven-env\Scripts\Activate.ps1
pip install serpmaven
patchright install chromium
serpmaven doctor

`doctor` ends with `ready` when the browser starts and looks like a desktop.

<details> <summary><b>On a Linux server (no screen)</b></summary>

<br>

The browser runs with a window, so a server needs a virtual display, and software WebGL when there is no GPU:

sudo apt install xvfb
sudo serpmaven-env/bin/patchright install-deps chromium
export SERPMAVEN_BROWSER_ARGS=--enable-unsafe-swiftshader
xvfb-run -a serpmaven doctor

Then start every command with `xvfb-run -a`. The [Docker image](#docker) has all of this built in.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 515 lines
  1. <div align="center">
  2. <img src="https://raw.githubusercontent.com/nodemaven/serpmaven/main/assets/banner.png" alt="SERP Maven">
  3. <h1>SERP Maven</h1>
  4. <p><b>Self-hosted SERP API alternative: search results from a real Chrome browser and your own residential proxy.</b></p>
  5. <p><code>pip install serpmaven</code>. Formerly <code>gserp</code> and <code>google-browser-scraper</code>: both now install serpmaven, and their old commands, imports and <code>GSERP_*</code> / <code>GBS_*</code> variables keep working.</p>
  6. [![pypi](https://img.shields.io/pypi/v/serpmaven?style=flat-square&cacheSeconds=3600)](https://pypi.org/project/serpmaven/)
  7. [![python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square)](https://pypi.org/project/serpmaven/)
  8. [![tests](https://img.shields.io/github/actions/workflow/status/nodemaven/serpmaven/ci.yml?branch=main&style=flat-square&label=tests)](https://github.com/nodemaven/serpmaven/actions/workflows/ci.yml)
  9. [![license](https://img.shields.io/pypi/l/serpmaven?style=flat-square&cacheSeconds=3600)](https://opensource.org/licenses/MIT)
  10. [![docker](https://img.shields.io/badge/docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/nodemaven/serpmaven/pkgs/container/serpmaven)
  11. [![2 GB free with code GOOGLENM](https://img.shields.io/badge/%F0%9F%8E%81%202%20GB%20free-code%20GOOGLENM-1153FC?style=flat-square)](https://dashboard.nodemaven.com/accounts/signup/?utm_source=github&utm_medium=readme&utm_campaign=google_browser_scraper&utm_content=promo_badge)
  12. <a href="https://devhunt.org/tool/google-search-scraper"><img src="https://devhunt.org/badge/google-search-scraper.svg" alt="SERP Maven on DevHunt" height="44"></a>
  13. [Quickstart](#quickstart) · [Output](#what-you-get) · [Poisoned results](#poisoned-results-protection) · [HTTP API](#run-it-as-an-api) · [MCP](#use-it-from-an-ai-agent-mcp) · [Docker](#docker) · [How it works](#how-it-works) · [Options](#options)
  14. </div>
  15. <br>
  16. <p align="center">
  17. <img src="https://raw.githubusercontent.com/nodemaven/serpmaven/main/assets/demo.gif" alt="A real Chrome window showing Google results next to the JSON the scraper produced for them" width="900">
  18. </p>
  19. <div align="center">
  20. | ✅ **100%** | 📉 **0.4 MB** | ⚡ **1.4 s** |
  21. |:---:|:---:|:---:|
  22. | success rate | per search | per search on a warm proxy IP |
  23. <sub>Latest version benchmarks (v0.1)</sub>
  24. </div>
  25. Scrape Google search results (SERP) with a real Chrome browser and your own
  26. residential proxy, and get clean JSON back. Use it as a CLI, a Python library,
  27. a local HTTP API, or an MCP server that gives AI agents live Google search.
  28. Plain HTTP is no longer a reliable way to scrape Google, and a fresh browser on a
  29. fresh proxy IP is refused quickly. So the scraper warms its first sticky proxy
  30. session with ordinary browsing and starts later ones from the cookies Google
  31. already accepts, lets the browser pass Google's checks, and then fetches results
  32. pages directly over HTTPS with the browser's own cookies. Captchas and
  33. blocks are reported as such, never as "no results".
  34. ## Features
  35. <table>
  36. <tr>
  37. <td width="50%" valign="top">
  38. ⚡ **Hybrid mode**<br>
  39. Results pages over HTTPS between Google's checks: a fraction of a browser's traffic and time. The browser takes over by itself when needed.
  40. </td>
  41. <td width="50%" valign="top">
  42. 🛡️ **Poisoned results protection**<br>
  43. Pages of results for some other query are caught: the proxy IP serving them is dropped within a few pages and the query is asked again on a fresh one.
  44. </td>
  45. </tr>
  46. <tr>
  47. <td valign="top">
  48. 🌐 **Real browser**<br>
  49. Real Chrome via Patchright, warmed up once and then carrying the cookies Google already trusts to every new identity, so Google's checks pass.
  50. </td>
  51. <td valign="top">
  52. 🧩 **SERP API-style JSON**<br>
  53. `organic_results`, `ads`, `related_questions`, `related_searches`, `pagination`, `ai_overview`, `local_results`.
  54. </td>
  55. </tr>
  56. <tr>
  57. <td valign="top">
  58. 🔌 **Bring your own proxy**<br>
  59. Any residential proxy with sticky sessions, built-in [NodeMaven](https://nodemaven.com/?utm_source=github&utm_medium=readme&utm_campaign=google_browser_scraper&utm_content=features) support.
  60. </td>
  61. <td valign="top">
  62. 🚦 **Honest failures**<br>
  63. Captchas and blocks come back labeled, not as empty results.
  64. </td>
  65. </tr>
  66. <tr>
  67. <td valign="top">
  68. 🤖 **For AI agents**<br>
  69. An MCP server that gives agents live Google search, with the AI Overview and map places.
  70. </td>
  71. <td valign="top">
  72. 🐳 **Run it your way**<br>
  73. CLI, Python library, HTTP API, MCP server or Docker image. Traffic and cost per 1000 pages in every run summary.
  74. </td>
  75. </tr>
  76. </table>
  77. ## Use cases
  78. - SEO rank tracking and SERP monitoring for your own keywords
  79. - Keyword and competitor research from live Google results
  80. - Web search for AI agents and LLM apps through MCP
  81. - A self-hosted alternative to paid Google search APIs when you already pay for proxies
  82. ## Install
  83. Python 3.10 or newer, in a virtual environment:
  84. ```bash
  85. python3 -m venv serpmaven-env
  86. source serpmaven-env/bin/activate
  87. pip install serpmaven
  88. patchright install chromium
  89. serpmaven doctor
  90. ```
  91. In PowerShell:
  92. ```powershell
  93. python -m venv serpmaven-env
  94. Set-ExecutionPolicy -Scope Process Bypass -Force # lets this window run Activate.ps1
  95. .\serpmaven-env\Scripts\Activate.ps1
  96. pip install serpmaven
  97. patchright install chromium
  98. serpmaven doctor
  99. ```
  100. `doctor` ends with `ready` when the browser starts and looks like a desktop.
  101. <details>
  102. <summary><b>On a Linux server (no screen)</b></summary>
  103. <br>
  104. The browser runs with a window, so a server needs a virtual display, and
  105. software WebGL when there is no GPU:
  106. ```bash
  107. sudo apt install xvfb
  108. sudo serpmaven-env/bin/patchright install-deps chromium
  109. export SERPMAVEN_BROWSER_ARGS=--enable-unsafe-swiftshader
  110. xvfb-run -a serpmaven doctor
  111. ```
  112. Then start every command with `xvfb-run -a`. The [Docker image](#docker) has
  113. all of this built in.
  114. </details>
  115. ## Quickstart
  116. > [!NOTE]
  117. > You need a residential proxy with **sticky sessions**. Put `{session}` where
  118. > your provider expects a session id in the username.
  119. ```bash
  120. serpmaven search "best running shoes" --proxy "http://USER-session-{session}:PASS@gate.example.com:7000" -o results.jsonl
  121. ```
  122. The first query takes a few minutes while the first proxy IP warms up on a few
  123. ordinary pages; the terminal shows each step. Later queries take seconds, and
  124. new proxy IPs start from its cookies. Every run ends with the pages served and
  125. the traffic used, warm-up apart from the pages.
  126. ### With NodeMaven
  127. The session id is handled for you and the credentials come from the environment:
  128. ```bash
  129. pip install "serpmaven[nodemaven]"
  130. export NODEMAVEN_LOGIN=... NODEMAVEN_PASSWORD=...
  131. printf "best running shoes\nhow to boil eggs\n" > queries.txt
  132. serpmaven search -f queries.txt --nodemaven --country us -o results.jsonl
  133. ```
  134. In PowerShell:
  135. ```powershell
  136. pip install "serpmaven[nodemaven]"
  137. $env:NODEMAVEN_LOGIN = "..."; $env:NODEMAVEN_PASSWORD = "..."
  138. Set-Content queries.txt "best running shoes", "how to boil eggs"
  139. serpmaven search -f queries.txt --nodemaven --country us -o results.jsonl
  140. ```
  141. > [!TIP]
  142. > 🎁 **2 GB of free traffic.** No NodeMaven account yet? [Sign up](https://dashboard.nodemaven.com/accounts/signup/?utm_source=github&utm_medium=readme&utm_campaign=google_browser_scraper&utm_content=signup_promo) and enter the code **GOOGLENM**. Once per account.
  143. <details>
  144. <summary><b>Cap a run's traffic with a demo sub-user</b></summary>
  145. <br>
  146. `--nodemaven-demo` creates a sub-user with a traffic limit from your dashboard API
  147. key, shares it across workers, and deletes it when the run ends (`--keep-subuser`
  148. keeps it). The account needs sub-users enabled. A fresh warm-up alone uses about
  149. 60 MB, so keep the cap well above that:
  150. ```bash
  151. export NODEMAVEN_API_KEY=...
  152. serpmaven search -f queries.txt --nodemaven-demo --traffic-limit-mb 300 -o results.jsonl
  153. ```
  154. </details>
  155. <details>
  156. <summary><b>Try it without a proxy</b></summary>
  157. <br>
  158. ```bash
  159. serpmaven search "best running shoes" --no-proxy
  160. ```
  161. Google then sees one address for every query, so it starts answering with
  162. captchas sooner than it would across a pool of proxy IPs. Those pages come back as
  163. `captcha` in `page_verdict`, not as empty results.
  164. </details>
  165. ### From Python
  166. ```python
  167. from serpmaven import ProxyTemplate, Scraper, Settings
  168. proxy = ProxyTemplate("http://USER-session-{session}:PASS@gate.example.com:7000")
  169. for page in Scraper(proxy, Settings(pages=2)).run(["best running shoes"]):
  170. for result in page.get("organic_results", []):
  171. print(result["position"], result["title"], result["link"])
  172. ```
  173. ## What you get
  174. One JSON object per results page:
  175. ```json
  176. {
  177. "search_metadata": {"status": "Success", "page_verdict": "ok", "fetched_with": "http"},
  178. "search_parameters": {"engine": "google", "q": "best running shoes", "page": 1},
  179. "organic_results": [
  180. {"position": 1, "title": "...", "link": "https://...", "snippet": "..."}
  181. ],
  182. "related_questions": [{"question": "..."}],
  183. "ai_overview": {"text": "..."},
  184. "exit": {"session": "...", "queries_on_exit": 1, "bytes": "..."}
  185. }
  186. ```
  187. The field names are the ones common to SERP APIs, so simple consumers can often
  188. switch with minimal mapping.
  189. <details>
  190. <summary><b>All fields</b></summary>
  191. <br>
  192. - `organic_results`, `ads`, `related_questions`, `related_searches`, `pagination`, `search_metadata`
  193. - `ai_overview`: the text of Google's AI Overview when the page shows one (pages in English, `--hl en`, the default)
  194. - `local_results`: the places of the map pack on local queries (name, rating, reviews, type, address, phone, opening hours)
  195. - `exit`: which proxy IP (sticky session) answered and how many bytes the page cost
  196. - `search_metadata.fetched_with`: `http` or `browser`
  197. - `search_metadata.timings`: seconds per step (`http` for a page fetched over HTTP; `type`, `load`, `ready` and `read` for one the browser rendered; `parse`; `links`, which overlaps the next query)
  198. - A query that failed is a record too, with an `error`
  199. Knowledge panels, shopping, images and other special blocks are not parsed.
  200. `--format csv` writes the organic results as a table, and `--price-per-gb` adds
  201. the cost per 1000 pages to the summary.
  202. </details>
  203. ## Poisoned results protection
  204. Google does not always block a scraper. Sometimes it answers with a normal-looking
  205. results page for a different query: no captcha, no error, just wrong data that
  206. slips into your pipeline unnoticed.
  207. The scraper checks results pages against the queries it asked. When a proxy IP
  208. starts returning unrelated results, it is dropped within a few pages and the query
  209. is asked again on a fresh one.
  210. - No extra requests, no extra traffic: the check runs on the page already downloaded
  211. - On by default
  212. ## Run it as an API
  213. ```bash
  214. serpmaven serve --nodemaven --country us --prewarm
  215. curl "http://127.0.0.1:8000/search.json?q=best+running+shoes"
  216. ```
  217. In PowerShell, call `curl.exe` (plain `curl` there is another command).
  218. - Same record format as above
  219. - `hl` (language) and `gl` (country) per request: `/search.json?q=...&hl=de&gl=at`
  220. - `--prewarm` finds a proxy IP Google serves at startup, so the first request does not wait for a warm-up; `/health` answers 503 `warming` until then
  221. - Results pages are read one at a time on one held proxy IP; a page's links resolve in the background, so the next request starts while the last one waits for its links
  222. - `links=N` resolves the links of the first N organic results only (`0`: none)
  223. - `links_wait=S` answers after S seconds with the links resolved by then; links still being resolved are `null` and counted in `search_metadata.links_pending`
  224. - `async=true` answers at once with `search_metadata.id`; `GET /searches/<id>.json` answers `"status": "Processing"` until the search and its links are done, then the record. The newest 500 searches are kept there, each for up to an hour; up to 50 async searches wait for the browser at once, more are answered 429
  225. - Set `SERPMAVEN_API_KEY` to require a key; without one the server only listens on localhost
  226. ## Use it from an AI agent (MCP)
  227. ```json
  228. {
  229. "mcpServers": {
  230. "google-search": {
  231. "command": "serpmaven",
  232. "args": ["mcp", "--nodemaven", "--country", "us", "--prewarm"],
  233. "env": {"NODEMAVEN_LOGIN": "...", "NODEMAVEN_PASSWORD": "..."}
  234. }
  235. }
  236. }
  237. ```
  238. One tool, `google_search(query, pages, hl, gl)`. It returns the organic results,
  239. "People also ask", related searches, and the AI Overview and map places when
  240. Google shows them.
  241. ## Docker
  242. A ready image is published to GitHub Container Registry with every release:
  243. ```bash
  244. docker run --rm ghcr.io/nodemaven/serpmaven doctor
  245. docker run --rm -p 8000:8000 -e SERPMAVEN_API_KEY=change-me \
  246. -e SERPMAVEN_PROXY='http://USER-session-{session}:PASS@gate.example.com:7000' \
  247. ghcr.io/nodemaven/serpmaven serve --host 0.0.0.0
  248. ```
  249. To build it yourself: `docker build -t serpmaven .`
  250. ## How it works
  251. 1. **New identity:** a sticky proxy session and a fresh browser profile.
  252. 2. **Warm-up:** the first proxy IP opens a few ordinary pages, staying on each
  253. for 20-45 seconds. Later ones start from the Google cookies of a served proxy
  254. IP and are warmed up only when no such set is accepted.
  255. 3. **Search:** the first query on a proxy IP goes through the browser. Once Google
  256. serves it, the next pages come over HTTPS with the browser's cookies, until
  257. Google asks for its check again.
  258. 4. **Check before parsing:** a captcha or a block is reported as one, never
  259. parsed as an empty result.
  260. 5. **Keep or drop:** a proxy IP Google answers is reused; one it refuses is dropped
  261. and the query retried on a new one. If one proxy IP after another is refused, the run
  262. stops instead of spending more traffic.
  263. <details>
  264. <summary><b>More detail: HTTP between checks, holding proxy IPs, copied cookies, result links, traffic</b></summary>
  265. <br>
  266. **HTTP between checks.** After the browser passes Google's check, results pages
  267. are fetched over HTTPS with the browser's own headers and cookies. If that stops
  268. working, the scraper goes back to the browser on its own. `--no-hybrid` uses the
  269. browser for every page.
  270. **Unrelated results.** A proxy IP that starts returning results unrelated to the
  271. queries is dropped, and the query is asked again on a new one.
  272. **Holding proxy IPs.** A served proxy IP is kept for up to 300 queries. Every new one
  273. pays for a browser check, and for a warm-up when no cookie set is accepted, so a
  274. short cap mostly buys more of that traffic. Every 50
  275. results pages it renders, the browser is restarted on the same profile and proxy IP, which keeps
  276. its memory from growing over a long hold. A browser error on a search is retried
  277. once on the same proxy IP before it is dropped; a network error, running out of
  278. memory or a crashed browser drops it at once.
  279. **Copying cookies.** With `--renew-cookies 0`, the command line copies the
  280. cookies of the first proxy IP Google serves and starts new proxy IPs from that
  281. copy, on new sticky sessions, instead of warming each one; all workers share
  282. the copy. Google's acceptance follows the cookies more than the address, so a
  283. copy usually starts out served and costs a few MB instead of a full warm-up. A
  284. copy waits 40-60 seconds after its browser starts before the first search.
  285. **Copying the cache.** Pages get cheaper as a proxy IP is held, because the
  286. browser cache fills with Google's shared scripts and images. Copies carry that
  287. cache too, so a new proxy IP starts with cheap pages, and the copy is refreshed
  288. from the held one at each browser restart, when its cache is warm. If two
  289. copies carrying the cache are refused on their first search, the rest of the
  290. run copies cookies only (`--no-clone-cache` does that from the start).
  291. **Starting from saved cookies.** `--cookies FILE` gives every new proxy IP the
  292. Google cookies of a browser Google already serves, so it skips the warm-up; the
  293. file can come from another machine. `--renew-cookies N` replaces that set with
  294. the cookies of a served proxy IP every N queries, so it stays fresh, and without
  295. `--cookies` it ends the warm-ups after the first renewal. It is on by default,
  296. every 25 queries, so a run warms up its first proxy IP and rarely another;
  297. `--renew-cookies 0` goes back to copies of the first served profile.
  298. `--cookies-out DIR` saves each renewed set for the next run, readable by its
  299. owner only. If every set is refused in turn, new proxy IPs are warmed up again,
  300. and with `--renew-cookies` the next renewal brings the sets back. A file is a
  301. JSON list of Playwright cookie records, or an object with that list under
  302. `"cookies"`, and must hold Google's `NID` cookie.
  303. **Result links.** Google wraps result links in encrypted `/goto` redirects.
  304. Each one is resolved with a small request on the proxy IP the page came from,
  305. with that page's cookies, in the background while the next query runs; a link
  306. left over is tried through a separate short-lived proxy session. Google answers
  307. only a few links of a page at once and holds the rest on a "Verifying your
  308. request" page; a link held for up to 30 seconds is asked again when the wait is
  309. over, twice at most and within 45 seconds a page, so a page's links can take up
  310. to 45 seconds while the queries carry on.
  311. Records still come out in the order each browser searched them.
  312. **Traffic.** Everything goes through a small local relay that counts bytes per
  313. host and refuses what no search needs: the models and data files Chrome
  314. otherwise downloads into every fresh profile, and the videos of a warm-up page.
  315. </details>
  316. The defaults come from measurements in
  317. [proxy-benchmark](https://github.com/nodemaven/proxy-benchmark).
  318. ## Options
  319. <details>
  320. <summary><b>All search options</b></summary>
  321. <br>
  322. | Option | Default | What it does |
  323. |---|---|---|
  324. | `--workers N` | 1 | Search on N proxy IPs at once, one browser each, from one list of queries |
  325. | `--max-per-exit N` | 300 | Queries before a served proxy IP is retired |
  326. | `--restart-every N` | 50 | Results pages the browser rendered before it restarts on the same profile and proxy IP; `0` never |
  327. | `--no-hybrid` | | Fetch every results page in the browser instead of over HTTP between Google's checks |
  328. | `--hl`, `--gl` | `en`, unset | Language and country of the results |
  329. | `--clone N` | 10 | With `--renew-cookies 0`: new proxy IPs started from copied cookies; `0` turns copying off |
  330. | `--clone-max-age` | 180 | Minutes copied cookies stay in use |
  331. | `--clone-refusals N` | 1 | Copies refused in a row on their first query that end the copying |
  332. | `--no-clone-cache` | | Copies carry cookies only, not the browser cache |
  333. | `--cookies FILE` | | Start every new proxy IP from the Google cookies in FILE instead of a warm-up; repeat for more files, the next one taking over after two proxy IPs in a row are refused on their first query, and warm-ups again once every file has been refused that way. Turns `--clone` off |
  334. | `--renew-cookies N` | 25 | Every N served queries, a proxy IP's Google cookies become the set new proxy IPs start from; `0` turns it off and brings back `--clone` |
  335. | `--cookies-out DIR` | | Write each renewed cookie set to DIR, for the next run's `--cookies` |
  336. | `--warmup` | `L3` | Pages a fresh proxy IP opens before its first query: `L3`, `light` (without Google Trends: much less traffic, served on the first query less often), `L2`, `L1`, `off` |
  337. | `--spare N` | 0 | Proxy IPs warmed in the background so a retired one is replaced at once; each costs a warm-up |
  338. | `--direct` | `all` | Open results pages directly: `all`, `follow-ups` (all but the first query on each proxy IP), `none` |
  339. | `--input` | `type` | How a query goes into the search box: `type`, `insert`, `words` |
  340. | `--gap LOW,HIGH` | 2,5 | Seconds between queries on one proxy IP |
  341. | `--pages N` | 1 | Result pages per query |
  342. | `--format` | `jsonl` | `jsonl` or `csv` |
  343. | `--price-per-gb` | | Your proxy price, to print the cost per 1000 pages |
  344. | `--no-resolve-links` | | Keep result links as Google `/goto` redirects |
  345. | `--save-html DIR` | | Keep every page's HTML, gzipped |
  346. `-v` prints every step as JSON instead, and the summary as one JSON line.
  347. `serpmaven search --help` lists the rest.
  348. </details>
  349. ## Proxies
  350. Any provider with sticky sessions works through `--proxy` and a `{session}`
  351. placeholder. A proxy without one is accepted with a warning: if the proxy IP changes
  352. on every request, warming it does nothing. SOCKS5 needs an IP-whitelisted
  353. endpoint, because Chrome cannot send a SOCKS5 username and password.
  354. ## Check your machine
  355. ```bash
  356. serpmaven doctor
  357. ```
  358. Starts the browser on a blank page, sends nothing, and reports what a website
  359. would see: whether the browser looks headless, whether WebGL works, the screen
  360. size. Google answers some machines much less than others, so run this first.
  361. ## What this is not
  362. Not a free Google Search API, and not a guarantee that every proxy IP will
  363. work. It is a browser-based collector that makes failures explicit, drops proxy IPs
  364. Google refuses, and tells you what each page cost.
  365. ## Status
  366. Early. The `cloak` engine (`--engine cloak`) is experimental; `patchright` is
  367. the default.
  368. Google changes its pages often. If results come back empty or wrong, run with
  369. `--save-html DIR` and open an issue with what you see.
  370. You are responsible for using this within Google's terms and the law where you
  371. run it.
  372. ## Adding an engine
  373. An engine joins this tool only after it has been measured on
  374. [proxy-benchmark](https://github.com/nodemaven/proxy-benchmark). Add it there
  375. and run the warm-up ladder against Google:
  376. ```bash
  377. python scripts/run_ladder.py --engines your-engine
  378. ```
  379. Then open a pull request here with the run file. The ladder runs identities
  380. with and without the warm-up in the same hours, so the result shows whether the
  381. engine actually gets served, not whether it got lucky once.
  382. ## License
  383. [MIT](https://github.com/nodemaven/serpmaven/blob/main/LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.