You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<ahref="https://www.searchapi.io/?utm_source=github&utm_medium=sponsorship&utm_campaign=google_search_api&utm_content=HarimxChoi_google-surf-mcp"><imgsrc="./assets/searchapi-banner.png"width="100%"alt="SearchApi Google Search API" /></a>
@@ -58,7 +63,7 @@ CAPTCHA는 사람이 직접 함 (프로필 평판 유지 → 지속가능한 운
58
63
59
64
## Install
60
65
61
-
Node 18+, 시스템에 Google Chrome (또는 Chromium) 필요
66
+
Node 18+ 필요. 브라우저 모드는 Google Chrome 또는 Chromium도 필요합니다.
62
67
63
68
```bash
64
69
npx google-surf-mcp # 실제 MCP, 클라이언트 config에 등록
@@ -103,6 +108,34 @@ Claude Code 재시작
103
108
104
109
다른 MCP 클라이언트도 같은 JSON 구조 그대로 (config 파일 경로만 다름)
105
110
111
+
## 검색 provider
112
+
113
+
기본값은 기존 브라우저 검색입니다. [SearchApi](https://www.searchapi.io/?utm_source=github&utm_medium=sponsorship&utm_campaign=google_search_api&utm_content=HarimxChoi_google-surf-mcp)를 메인 provider 또는 브라우저 실패 시 fallback으로 설정할 수 있습니다.
114
+
115
+
| 값 | 동작 |
116
+
|---|---|
117
+
|`browser`| 기본값. 기존 Google Surf 브라우저 경로를 사용하며 `SEARCH_API`가 필요하지 않습니다. |
118
+
|`searchapi`| SearchApi를 메인 provider로 사용합니다. 해당 도구 실행 시 Chrome을 초기화하지 않습니다. |
119
+
|`fallback`| 브라우저를 먼저 사용합니다. 브라우저 오류, CAPTCHA나 rate limit, 프로필 실패, 파서 열화 시에만 SearchApi로 전환합니다. 성공 응답과 정상적인 빈 결과는 다시 요청하지 않습니다. |
120
+
121
+
`SURF_SEARCH_PROVIDER`는 `search`, `search_parallel`에 적용됩니다. `SURF_SCHOLAR_PROVIDER`는 `scholar_search`에 적용됩니다. SearchApi 모드는 본인의 SearchApi 계정, API 키, 사용 가능한 크레딧이 필요합니다.
122
+
123
+
```json
124
+
{
125
+
"mcpServers": {
126
+
"google-surf": {
127
+
"command": "npx",
128
+
"args": ["-y", "google-surf-mcp"],
129
+
"env": {
130
+
"SEARCH_API": "your-searchapi-key",
131
+
"SURF_SEARCH_PROVIDER": "fallback",
132
+
"SURF_SCHOLAR_PROVIDER": "searchapi"
133
+
}
134
+
}
135
+
}
136
+
}
137
+
```
138
+
106
139
로컬 클론 사용 시:
107
140
```json
108
141
{
@@ -117,8 +150,9 @@ Claude Code 재시작
117
150
118
151
## Tools
119
152
120
-
-`search(query, limit?)` - 단일 검색, ~1.5초. title / url / snippet 반환. 스폰서 광고 + 지식 패널 자동 제거 (응답에 `dropped` 카운트 + `dropped_reasons` 포함). 결과 24h 캐시 (`SURF_CACHE_TTL_SEARCH_MS=0`으로 우회)
121
-
-`search_parallel(queries[], limit?)` - 4-워커 풀, 호출당 최대 10개 쿼리
153
+
-`search(query, limit?)` - 브라우저 모드 기준 단일 검색, ~1.5초. title / url / snippet 반환. 브라우저 경로에서는 스폰서 광고와 지식 패널을 제거합니다. 결과 24h 캐시 (`SURF_CACHE_TTL_SEARCH_MS=0`으로 우회)
154
+
-`scholar_search(query, limit?)` - Google Scholar 논문 검색, 최대 10개. 저자, 출판 정보, 연도, 초록 일부, 인용 수, 관련 논문/버전 링크, 원문 링크 반환. 브라우저, SearchApi 메인, fallback 모드를 지원합니다.
155
+
-`search_parallel(queries[], limit?)` - 브라우저 모드에서는 4-워커 풀을 사용합니다. 호출당 최대 10개 쿼리이며 `SURF_SEARCH_PROVIDER`를 따릅니다.
<ahref="https://www.searchapi.io/?utm_source=github&utm_medium=sponsorship&utm_campaign=google_search_api&utm_content=HarimxChoi_google-surf-mcp"><imgsrc="./assets/searchapi-banner.png"width="100%"alt="SearchApi Google Search API" /></a>
15
+
</p>
16
+
<palign="center">Sponsored by <ahref="https://www.searchapi.io/?utm_source=github&utm_medium=sponsorship&utm_campaign=google_search_api&utm_content=HarimxChoi_google-surf-mcp">SearchApi</a></p>
17
+
13
18
14
19
15
20
> Demo only. Actual searches run **headless** by default (no visible browser). Set `SURF_HEADLESS=false` to make Chrome visible like in the clip above.
16
21
17
-
Google search MCP. No API key. Just works.
22
+
Google search MCP. Browser mode needs no API key. SearchApi is optional.
@@ -60,7 +65,7 @@ Measured on a workstation with a 1Gb/s connection.
60
65
61
66
## Install
62
67
63
-
Requires Node 18+ and Google Chrome (or Chromium) on the system.
68
+
Requires Node 18+. Browser mode also requires Google Chrome or Chromium.
64
69
65
70
```bash
66
71
npx google-surf-mcp # actual MCP - register in client config
@@ -101,10 +106,38 @@ Paste this into your `~/.claude.json`:
101
106
}
102
107
```
103
108
104
-
Restart Claude Code. Done. `search`, `search_parallel`, `extract`, `search_extract`, `health` are now available.
109
+
Restart Claude Code. Done. `search`, `scholar_search`, `search_parallel`, `extract`, `search_extract`, `health` are now available.
105
110
106
111
For other MCP clients, use the same JSON shape in their config file.
107
112
113
+
## Search providers
114
+
115
+
Browser search remains the default. [SearchApi](https://www.searchapi.io/?utm_source=github&utm_medium=sponsorship&utm_campaign=google_search_api&utm_content=HarimxChoi_google-surf-mcp) can be selected as the primary provider or used only when browser search fails.
116
+
117
+
| value | behavior |
118
+
|---|---|
119
+
|`browser`| Default. Uses the existing Google Surf browser path and does not require `SEARCH_API`. |
120
+
|`searchapi`| Uses SearchApi as the primary provider and does not initialize Chrome for that tool. |
121
+
|`fallback`| Uses the browser first, then SearchApi on browser errors, CAPTCHA/rate limits, profile failure, or parser degradation. Successful and normal empty browser responses are not repeated. |
122
+
123
+
`SURF_SEARCH_PROVIDER` controls `search` and `search_parallel`. `SURF_SCHOLAR_PROVIDER` controls `scholar_search`. SearchApi modes require your own SearchApi account, key, and available credits.
124
+
125
+
```json
126
+
{
127
+
"mcpServers": {
128
+
"google-surf": {
129
+
"command": "npx",
130
+
"args": ["-y", "google-surf-mcp"],
131
+
"env": {
132
+
"SEARCH_API": "your-searchapi-key",
133
+
"SURF_SEARCH_PROVIDER": "fallback",
134
+
"SURF_SCHOLAR_PROVIDER": "searchapi"
135
+
}
136
+
}
137
+
}
138
+
}
139
+
```
140
+
108
141
Local clone variant:
109
142
```json
110
143
{
@@ -119,8 +152,9 @@ Local clone variant:
119
152
120
153
## Tools
121
154
122
-
-`search(query, limit?)` - single query, ~1.5s. Returns title / url / snippet. Sponsored ads + knowledge-panel dropped (response includes `dropped` count + `dropped_reasons`). Results cached 24h (`SURF_CACHE_TTL_SEARCH_MS=0` to bypass).
123
-
-`search_parallel(queries[], limit?)` - pool of 4, max 10 queries per call.
155
+
-`search(query, limit?)` - single query, ~1.5s in browser mode. Returns title / url / snippet. Sponsored ads + knowledge-panel dropped on the browser path. Results cached 24h (`SURF_CACHE_TTL_SEARCH_MS=0` to bypass).
156
+
-`scholar_search(query, limit?)` - Google Scholar search, max 10 papers. Returns authors, publication, year, snippet, citation count, related/version links, and an available full-text link. Supports browser, SearchApi primary, and fallback modes.
157
+
-`search_parallel(queries[], limit?)` - pool of 4 in browser mode, max 10 queries per call. Follows `SURF_SEARCH_PROVIDER`.
124
158
-`extract(url, max_chars?, mode?)` - fetch a URL, return article content.
125
159
-`mode="full"` (default): whole body. HTML via Readability, PDFs via `liteparse` (spatial parsing, multi-column reading order).
126
160
-`mode="abstract"`: ~1500-char survey (PDF page 1 or HTML meta description). Triage relevance before paying for full text.
@@ -133,6 +167,10 @@ Local clone variant:
133
167
134
168
| var | default | notes |
135
169
|---|---|---|
170
+
|`SEARCH_API`| unset | SearchApi API key. Required only when either provider setting is `searchapi` or `fallback`. Sent as a bearer token and never placed in the request URL. |
171
+
|`SEARCHAPI_API_KEY`| unset | Alias for `SEARCH_API`. |
172
+
|`SURF_SEARCH_PROVIDER`|`browser`| Provider for `search` and `search_parallel`: `browser`, `searchapi`, or `fallback`. |
173
+
|`SURF_SCHOLAR_PROVIDER`|`browser`| Provider for `scholar_search`: `browser`, `searchapi`, or `fallback`. |
136
174
|`CHROME_PATH`| auto-detected | absolute path to Chrome binary |
137
175
|`SURF_PROFILE_ROOT`|`~/.google-surf-mcp`| where the warm profile lives |
138
176
|`SURF_LOCALE`|`en-US`| browser locale |
@@ -146,7 +184,7 @@ Local clone variant:
146
184
|`SURF_CLOUD_MODE`|`false`| headless/serverless mode: TLS bypass + `--no-sandbox` + `--disable-dev-shm-usage` + worker pool disabled + fail-fast on CAPTCHA |
147
185
|`SURF_CASCADE_DISABLED`|`false`| pin a single stealth mode (chosen by `SURF_USE_STEALTH`) instead of the 3-tier auto-cascade |
148
186
|`SURF_USE_STEALTH`|`true`| initial stealth tier — only consulted when `SURF_CASCADE_DISABLED=true`|
149
-
|`SURF_HUMANLIKE_MODE`|`off`|`off` / `background` (fire-and-forget after returning results) / `inline` (await before returning, slower) — opt-in humanlike browsing|
187
+
|`SURF_HUMANLIKE_MODE`|`background`|`off` / `background` (fire-and-forget after returning results) / `inline` (await before returning, slower) |
150
188
|`SURF_RATE_LIMIT_PER_MIN`|`10`| internal cap on Google-facing requests per minute |
"description": "Free Google search MCP that actually works — no API key, no proxies, no solvers. Search + extraction in one MCP.",
7
-
"long_description": "Free Google search MCP that actually works — no API key, no proxies, no solvers (most free Google search MCPs fail in practice; this one drives a warm Chrome profile via Playwright + stealth). Search + page extraction in one MCP: `search_extract` returns SERP results already enriched with article bodies — replaces the usual search-MCP + fetch-MCP combo. CAPTCHA opens a visible Chrome window for a human to solve (shared-IP reputation protection); `SURF_CLOUD_MODE=true` for headless/serverless fail-fast.",
6
+
"version": "0.8.0",
7
+
"description": "Google and Google Scholar search with browser and optional SearchApi providers.",
8
+
"long_description": "Google and Google Scholar search with page extraction. Browser mode uses a warm Chrome profile and requires no API key. SearchApi can be configured as the primary provider or as fallback for browser errors, CAPTCHA, rate limits, profile failure, and parser degradation.",
"description": "Single Google search -> title/url/snippet per result. Results cached 24h. First call ~4s, then ~2s. On CAPTCHA opens visible Chrome for human solving; SURF_CLOUD_MODE=true for fail-fast."
63
+
"description": "Single Google search via browser, SearchApi primary, or browser-to-SearchApi fallback. Returns title, URL, and snippet."
64
+
},
65
+
{
66
+
"name": "scholar_search",
67
+
"description": "Google Scholar search via browser, SearchApi primary, or fallback. Returns paper metadata, citations, links, and available full text."
60
68
},
61
69
{
62
70
"name": "search_parallel",
63
-
"description": "Run 2-10 Google searches concurrently. Rate-limited (~10/min). Disabled in cloud mode."
71
+
"description": "Run 2-10 Google searches using the provider selected by SURF_SEARCH_PROVIDER. SearchApi works in cloud mode."
64
72
},
65
73
{
66
74
"name": "extract",
@@ -76,6 +84,27 @@
76
84
}
77
85
],
78
86
"user_config": {
87
+
"search_api_key": {
88
+
"type": "string",
89
+
"title": "SearchApi API key",
90
+
"description": "Required only for SearchApi primary or fallback modes.",
91
+
"sensitive": true,
92
+
"required": false
93
+
},
94
+
"search_provider": {
95
+
"type": "string",
96
+
"title": "Google search provider",
97
+
"description": "browser, searchapi, or fallback.",
98
+
"default": "browser",
99
+
"required": false
100
+
},
101
+
"scholar_provider": {
102
+
"type": "string",
103
+
"title": "Google Scholar provider",
104
+
"description": "browser, searchapi, or fallback.",
0 commit comments