内容
# gemini-search-mcp
<p align="center">
<img src="banner.png" width="700" alt="gemini-search-mcp">
</p>
<p align="center">
<img src="logo.png" width="120" alt="logo">
</p>
<p align="center">
基于谷歌 AI 模式（Gemini）的网络搜索 MCP 服务器。免费、无限额、无需 API 密钥。
</p>
## 什么是本项目
本项目是一个 MCP 服务器，允许任何 AI 代理（Claude、Cursor、Windsurf 等）使用谷歌的 AI 模式进行实时网络搜索，该模式与谷歌搜索中的“AI 模式”选项卡相同。
可以将其视为一种免费、无限额的 Grok MCP / Tavily / SerpAPI 替代方案，背后是谷歌的搜索索引。
## 功能特点
- **免费**: 无需 API 密钥、无需订阅、无限额
- **无限额**: 60+ 请求/分钟，无速率限制
- **谷歌质量**: 由 Gemini + 谷歌搜索驱动（基于真实网络结果）
- **MCP 原生**: 与 Claude Desktop、Claude Code、Cursor、Windsurf、Cline 兼容
- **也支持 OpenAI API**: `/v1/chat/completions` 接口，适用于非 MCP 客户端
- **快速**: 平均响应时间约为 1.5 秒
## 快速开始
```bash
pip install playwright fastapi uvicorn "mcp[cli]"
playwright install chrome
```
### MCP 服务器（适用于 AI 代理）
```bash
python mcp_server.py
```
### OpenAI 兼容 API
```bash
python -m gemini_search --port 8080
```
## MCP 集成
### Claude Code
```bash
claude mcp add gemini-search -- python /path/to/gemini-search-mcp/mcp_server.py
```
### Claude Desktop
添加到 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"gemini-search": {
"command": "python",
"args": ["/path/to/gemini-search-mcp/mcp_server.py"],
"env": {
"CDP_URL": "http://127.0.0.1:9222"
}
}
}
}
```
### Cursor / Windsurf
采用相同模式 — 将 `mcp_server.py` 作为 stdio MCP 服务器。
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `web_search(query)` | 搜索网络并获取基于实时结果的综合答案 |
| `ask(prompt)` | 一般问题 — AI 模式自动决定是否搜索网络 |
### 示例
```
web_search("latest AI regulation news 2026")
→ "欧盟 AI 法案于 2026 年 6 月 1 日开始执行，要求..."
web_search("Bitcoin price today")
→ "截至 2026 年 6 月 30 日，比特币交易价格为 59,687 美元..."
ask("what is 1847 * 293")
→ "541171"
```
## OpenAI API 使用
```bash
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"gemini-search","messages":[{"role":"user","content":"What happened in the news today?"}]}'
```
| 字段 | 值 |
|-------|-------|
| 基础 URL | `http://localhost:8080/v1` |
| API 密钥 | 任意值 |
| 模型 | `gemini-search` |
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CDP_URL` | （无） | Chrome DevTools URL。如果设置，则连接到现有的 Chrome 而不是启动新的 Chrome |
| `BROWSER_CHANNEL` | `chrome` | 要使用的浏览器：`chrome`、`msedge`、`chromium` |
| `HEADLESS` | `1` | 设置为 `0` 以显示浏览器窗口 |
## 工作原理
谷歌根据 TLS 指纹质量（而非 IP 地址）进行速率限制。自动化的 HTTP 客户端（curl、requests、httpx）在几个请求后会被限速。但真实的 Chrome 浏览器的 `fetch()` 调用是完全信任的。
该工具运行一个 Playwright 页面，并在其中执行所有查询作为 `fetch()`，为每个请求提供真实的 Chrome TLS/HTTP2 指纹。谷歌会将此视为正常的浏览器流量，不会应用速率限制。
```
代理调用 web_search("query")
→ Playwright page.evaluate(fetch)
→ 谷歌搜索 AI 模式（令牌提取 + folwr 端点）
→ 从 HTML 响应中解析答案
→ 返回给代理
```
## 比较
| | gemini-search-mcp | Grok MCP | Tavily |
|---|---|---|---|
| 成本 | **免费** | xAI API 密钥（$） | API 密钥（$） |
| 速率限制 | **无** | API 限额 | API 限额 |
| 搜索后端 | 谷歌搜索 | Grok + 网络 | 专有 |
| 答案质量 | Gemini 综合 | Grok 综合 | 提取的片段 |
| 设置 | Chrome + playwright | API 密钥 | API 密钥 |
## Docker
```bash
docker compose up -d
```
## 要求
- Python 3.10+
- Chrome、Edge 或 Chromium
- `playwright`、`fastapi`、`uvicorn`、`mcp[cli]`
## 限制
- 需要已安装 Chrome/Edge/Chromium
- 请求之间无对话内存
- 答案提取依赖于谷歌的 DOM 结构（可能会在更新时中断）
- 流式传输是分段的，而不是按令牌
## 致谢
- [GenericAgent](https://github.com/lsdefine/GenericAgent) — 本项目核心开发依仗 GA 提供的 AI 能力
- [linux.do](https://linux.do) 社区
## 许可证
MIT
