[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-131":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":34,"readmeContent":35,"aiSummary":36,"trendingCount":16,"starSnapshotCount":16,"syncStatus":15,"lastSyncTime":37,"discoverSource":38},131,"google-surf-mcp","HarimxChoi\u002Fgoogle-surf-mcp","HarimxChoi","Google search MCP. One MCP replaces search + fetch + academic-paper extractor.","",null,"TypeScript",226,26,144,2,0,7,9,74,21,4.29,"MIT License",false,"main",true,[27,28,29,30,31,32,33],"anti-bot","claude","google-search","mcp","model-context-protocol","no-api-key","playwright","2026-06-12 02:00:08","# google-surf-mcp\n\n✨Anti-Bot Search MCP: No API Key✨\n\nEnglish | [한국어](.\u002FREADME.ko.md)\n\n[![google-surf-mcp MCP server](https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002FHarimxChoi\u002Fgoogle-surf-mcp\u002Fbadges\u002Fscore.svg)](https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002FHarimxChoi\u002Fgoogle-surf-mcp)\n\n![demo](.\u002Fassets\u002Fdemo.gif)\n\n> Demo only. Actual searches run **headless** by default (no visible browser). Set `SURF_HEADLESS=false` to make Chrome visible like in the clip above.\n\nGoogle search MCP. No API key. Just works.\n\n- ✅ Actually works (tested 6 free Google search MCPs, all failed)\n- ✅ Search + URL extract in one MCP (replaces the usual search MCP + fetch MCP combo)\n- ✅ 4 tools: `search` \u002F `search_parallel` \u002F `extract` \u002F `search_extract`\n- ✅ No API key, no proxies, no solver\n- ✅ Auto CAPTCHA recovery (Chrome opens, human solves once, call retries)\n- ✅ SSRF guard on `extract` (blocks `localhost`, private IPs, AWS metadata by default)\n\n## What\n\nPlug it into any MCP client and you get Google search as a tool.\n\nNo CAPTCHA solver. When CAPTCHA fires on any tool, a Chrome window opens for a human to solve. Each solve preserves the profile's reputation with Google. Built for sustainable, ethical use.\n\nOne-time install needs a ~1s profile warm-up (see Install).\n\nDesigned for local use. Not suitable for stateless \u002F serverless deployment.\n\n## Numbers\n\n| | result |\n|---|---|\n| sequential | ~1.5s\u002Fquery (first call ~4s, includes setup) |\n| parallel x4 | ~1.5s wall (first call ~9s, includes pool warm) |\n| parallel x10 | ~4.5s wall |\n| search_extract x5 | ~5s wall (search + 5 parallel extracts) |\n\nMeasured on a workstation with a 1Gb\u002Fs connection.\n\n## Stack\n\n- Playwright + persistent Chrome profile\n- `playwright-extra` stealth\n- Resource-blocked images \u002F media \u002F fonts for speed\n- One-shot profile bootstrap before first run\n- Mozilla Readability + Turndown for article extraction\n\n## Install\n\nRequires Node 18+ and Google Chrome (or Chromium) on the system.\n\n```bash\nnpx google-surf-mcp   # actual MCP - register in client config\n```\n\nOr local clone:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FHarimxChoi\u002Fgoogle-surf-mcp\ncd google-surf-mcp\nnpm install\nnpm run bootstrap\n```\n\n`bootstrap` opens a Chrome window. Run one Google search in it. Close. Profile is now warm.\n\nOverride paths if needed:\n```bash\nCHROME_PATH=\u002Fpath\u002Fto\u002Fchrome SURF_TZ=America\u002FNew_York npm run bootstrap\n```\n\n## Use with Claude Code\n\nPaste this into your `~\u002F.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-surf\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"google-surf-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Code. Done. `search`, `search_parallel`, `extract`, `search_extract` are now available.\n\nFor other MCP clients, use the same JSON shape in their config file.\n\nLocal clone variant:\n```json\n{\n  \"mcpServers\": {\n    \"google-surf\": {\n      \"command\": \"node\",\n      \"args\": [\"\u002Fabs\u002Fpath\u002Fto\u002Fgoogle-surf-mcp\u002Fbuild\u002Findex.js\"]\n    }\n  }\n}\n```\n\n## Tools\n\n- `search(query, limit?)` - single query, ~1.5s. Returns title \u002F url \u002F snippet. Sponsored ads filtered out.\n- `search_parallel(queries[], limit?)` - pool of 4, max 10 queries per call.\n- `extract(url, max_chars?)` - fetch a URL, return article markdown (Readability with text fallback). Failures return `{ error }`, never throw.\n- `search_extract(query, limit?, max_chars?)` - search + parallel extract in one call. Returns SERP results enriched with full article content. Per-page failures are isolated.\n\n`search_extract` is the killer one: SERP + full article content in a single call. Replaces the usual \"search MCP + URL fetcher MCP\" combo most agents stitch together.\n\n## Env vars\n\n| var | default | notes |\n|---|---|---|\n| `CHROME_PATH` | auto-detected | absolute path to Chrome binary |\n| `SURF_PROFILE_ROOT` | `~\u002F.google-surf-mcp` | where the warm profile lives |\n| `SURF_LOCALE` | `en-US` | browser locale |\n| `SURF_TZ` | system tz | e.g. `America\u002FNew_York` |\n| `SURF_HEADLESS` | `true` | set `false` to run Chrome visibly (demos \u002F debugging). CAPTCHA auto-recovery always runs visible regardless. |\n| `SURF_IDLE_CLOSE_MS` | `30000` | idle ms before closing the sequential ctx and pool. `0` disables idle auto-close. Lower = faster cleanup, higher = warmer cache for spaced-out calls. |\n| `SURF_ALLOW_PRIVATE` | `false` | set `true` to allow `extract` to fetch private\u002Floopback addresses (`localhost`, `127.0.0.1`, `10.x`, `192.168.x`, `169.254.x`, etc). Default blocks them as an SSRF guard. |\n\n## Troubleshooting\n\n- CAPTCHA: a visible Chrome window opens automatically (works for all 4 tools). Solve it once, do one search inside, the call retries and continues. To fail-fast instead, run with no display attached.\n- \"Chrome not found\": install Chrome or set `CHROME_PATH`.\n- Stale selectors: Google rotates classes. PRs welcome.\n\n## Changelog\n\nSee [CHANGELOG.md](.\u002FCHANGELOG.md).\n\n## License\n\nMIT\n","google-surf-mcp 是一个无需 API 密钥即可进行 Google 搜索的项目。它通过 Playwright 和持久化的 Chrome 配置文件实现自动化搜索，支持搜索和 URL 提取功能，并且内置了自动处理验证码的功能。该项目提供了四种工具：`search`、`search_parallel`、`extract` 和 `search_extract`，能够满足不同的搜索需求。适合需要频繁使用 Google 搜索但又不想依赖于 API 密钥或代理服务器的场景，特别适用于本地环境下的开发和测试。由于其设计初衷是为本地使用而优化，因此不推荐在无状态或服务器端部署中使用。","2026-06-11 02:31:01","CREATED_QUERY"]