Serper Search MCP

---

功能介绍

此 MCP 服务封装了 Serper API（Google 搜索结果），并提供 14 个工具，供任何兼容 MCP 的 AI 客户端（Claude、Cursor、Windsurf、KiloCode、n8n 等）实时调用 — 涵盖网页、图片、视频、新闻、购物、地点、学术、专利、自动补全、整页抓取和批量搜索。

工具	功能
search ⭐	统一搜索 {type, provider, verbosity} — 1 个 schema（约 700 个 Token，而全部工具约需 7k）
search_web	自然搜索结果 + 知识图谱 + 答案框 + “大家还在问” + 相关搜索
search_images	图片 URL、缩略图、尺寸、来源页面 + gallery 布局 + size/orientation/color/site
search_videos	标题、频道、时长、链接
search_news	新闻标题、来源、日期 — 按时效筛选
search_shopping	商品、价格、评分、配送信息（始终提供丰富结果）
search_places	本地商家和兴趣点，含地址、电话、完整 7 天营业时间、GPS + 路线指引（始终提供丰富结果）
search_scholar 🆕	学术论文，含作者、期刊、年份和引用次数
search_patents 🆕	专利，含公开编号、受让人、发明人和日期
autocomplete 🆕	查询补全 — 成本低，无需大模型
scrape 🆕	以 Markdown 格式获取完整页面内容 — 阅读通过搜索找到的文章
search_many 🆕	并行执行 1–10 次网页搜索，并自动跨查询去重
deep_research	多步研究：自动生成子查询 → 并行搜索 → 由大模型合成带引用的报告
search_rag_context	为嵌入流水线和向量数据库提供带元数据的整洁分块文本 — 无需大模型

详细程度（节省 Token，默认自动选择）

模式	适用对象	内容	Token 数
auto（默认）	由服务端选择	开发→精简，聊天→标准，学术/研究→完整，地点/购物/图片→始终丰富	不定
compact	开发编码	标题+URL+单行摘要，不含 KG/PAA/相关搜索	~800
standard	普通聊天	知识图谱 + 答案框 + 10 条自然搜索结果	~4k
full	研究者	全部内容 + 引用	~5k

额度规则：compact 获取 num=5（绝不先获取 10 条再只展示 3 条）。1 次搜索 = 1 个额度，命中缓存 = 0，抓取 ≈ 2。deep_research：基础 3 个额度 / 标准 5 个额度 / 深度 8 个额度。

提供商（通用网关 — 自动故障转移）

提供商	每 1k 次的费用	适用场景
Serper（默认）	$3-5，每月免费 2500 次	最便宜的 Google 真实结果 — 保持首选
Tavily 后备	$8-16	AI 重新排序，适合金融/新闻主题
Brave 后备	$5	独立索引、注重隐私、669ms
Exa 后备	$4-7	关键词搜索无效时使用神经语义搜索
Firecrawl 后备	有效费用约 $3-4	JS 渲染抓取和搜索升级

SEARCH_PROVIDER_ORDER=serper,tavily,brave,exa  # failover chain
SEARCH_FALLBACK=true                           # on 402/429/5xx/empty

CLI（开发利器 — 比 MCP schema 便宜 4-32 倍）

npx serper-search-mcp search "react server components" --compact --limit 5
npx serper-search-mcp scrape https://example.com --max-chars 8000
npx serper-search-mcp research "RAG limits" --depth basic
npx serper-search-mcp rag "transformer" --format json
npx serper-search-mcp providers --status

**免费开始：**Serper 每月提供 2,500 次免费查询。无需信用卡。

---

快速开始

🔑 供应商密钥与通用网关配置

此服务充当通用搜索网关。只需设置 SERPER_API_KEY。你可以添加其他 4 个搜索供应商和大模型密钥中的任意组合，以启用自动多供应商故障切换、语义搜索和抓取升级：

变量	供应商／用途	默认值／优先级
SERPER_API_KEY	Serper（Google 搜索基准）	必需（serper.dev）
TAVILY_API_KEY	Tavily（AI 重新排序的备用选项）	可选（tavily.com）
BRAVE_API_KEY	Brave（独立网页索引备用选项）	可选（brave.com/search/api）
EXA_API_KEY	Exa（神经语义搜索备用选项）	可选（exa.ai）
FIRECRAWL_API_KEY	Firecrawl（JS 渲染抓取与搜索升级）	可选（firecrawl.dev）
OPENROUTER_API_KEY	用于 deep_research 的大模型	可选（优先于 Gemini）
GEMINI_API_KEY	用于 deep_research 的大模型	可选（未设置 OpenRouter 时使用）

故障切换控制：

SEARCH_PROVIDER_ORDER=serper,tavily,brave,exa  # custom failover priority chain
SEARCH_FALLBACK=true                           # auto-failover on 402/429/5xx/empty (default: true)

---

选项 1 — npx（MCP 客户端配置）

将以下内容添加到你的 MCP 客户端配置文件中（Claude Desktop、Cursor、Windsurf、KiloCode）。

🌟 完整通用网关配置（全部 5 个供应商 + 故障切换）：

{
  "mcpServers": {
    "serper-search": {
      "command": "npx",
      "args": ["-y", "serper-search-mcp"],
      "env": {
        "SERPER_API_KEY": "${SERPER_API_KEY}",
        "TAVILY_API_KEY": "${TAVILY_API_KEY}",
        "BRAVE_API_KEY": "${BRAVE_API_KEY}",
        "EXA_API_KEY": "${EXA_API_KEY}",
        "FIRECRAWL_API_KEY": "${FIRECRAWL_API_KEY}",
        "OPENROUTER_API_KEY": "${OPENROUTER_API_KEY}",
        "SEARCH_PROVIDER_ORDER": "serper,tavily,brave,exa",
        "SEARCH_FALLBACK": "true"
      }
    }
  }
}

（你可以省略不使用的供应商密钥；服务会自动检测已配置的供应商，并跳过未配置的供应商。）

最简配置（仅 Serper）：

{
  "mcpServers": {
    "serper-search": {
      "command": "npx",
      "args": ["-y", "serper-search-mcp"],
      "env": {
        "SERPER_API_KEY": "your_serper_key_here"
      }
    }
  }
}

---

选项 2 — Docker

docker run -i --rm \
  -e SERPER_API_KEY \
  -e TAVILY_API_KEY \
  -e BRAVE_API_KEY \
  -e EXA_API_KEY \
  -e FIRECRAWL_API_KEY \
  -e OPENROUTER_API_KEY \
  smjahid/server-serper-search:4

HTTP 模式（远程服务或云端）：

docker run --rm -p 8080:8080 \
  -e SERPER_API_KEY \
  -e SERPER_MCP_TRANSPORT=http \
  -e SERPER_MCP_HOST=0.0.0.0 \
  -e SERPER_MCP_AUTH_TOKEN="your_secure_bearer_token" \
  smjahid/server-serper-search:4

---

选项 3 — Shell 与命令行（PowerShell / Bash / CMD）

PowerShell（Windows）：

$env:SERPER_API_KEY = "your_key"
$env:TAVILY_API_KEY = "your_key"      # optional
$env:OPENROUTER_API_KEY = "your_key"  # optional
node index.js

Bash / macOS / Linux：

export SERPER_API_KEY="your_key"
export TAVILY_API_KEY="your_key"      # optional
export OPENROUTER_API_KEY="your_key"  # optional
node index.js

Windows 命令提示符：

set SERPER_API_KEY=your_key
node index.js

💡 AI 驱动的研究免费提供。 deep_research 默认使用 Gemini 免费层级。在上方设置 GEMINI_API_KEY 即可启用。

---

配置文件位置

客户端	配置路径
Claude Desktop（Mac）	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop（Win）	%APPDATA%\Claude\claude_desktop_config.json
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
KiloCode	~/.config/kilo/kilo.json（全局）或 <project>/kilo.json（项目）
n8n	MCP Client 节点 → 服务 URL

---

工具参考

search_web

Google 网页搜索，提供完整的 SERP 详细结果。

{
  "query":       "best mechanical keyboards 2025",   // required
  "num_results": 10,        // 1–20, default 10
  "country":     "US",      // ISO 3166-1 alpha-2
  "search_lang": "en",      // language code
  "freshness":   "pw",      // "pd" day · "pw" week · "pm" month · "py" year
  "safesearch":  "moderate",// "off" · "moderate" · "strict"
  "autocorrect": true,
  "summary":     false,     // Serper AI summary
  "page":        1          // pagination
}

响应包括：

• 🎯 答案框 — 有可用答案时直接显示
• 🧠 知识图谱 — 实体信息（类型、描述、评分、网站、属性）
• 🌐 自然搜索结果 — 标题、URL、摘要、站点链接、日期
• 💬 其他人还问了 — 最多 4 个后续问题及其答案
• 🔗 相关搜索 — 最多 6 条建议

---

search_images

{
  "query":       "minimalist desk setup",
  "num_results": 10,
  "country":     "US",
  "safesearch":  "moderate"
}

返回：图片 URL、缩略图、尺寸（宽 × 高）、来源域名、来源页面 URL。

---

search_videos

{
  "query":       "react server components tutorial",
  "num_results": 5,
  "freshness":   "pm"
}

返回：标题、频道、时长、发布日期、视频 URL。

---

search_news

{
  "query":       "OpenAI GPT-5 release",
  "num_results": 10,
  "freshness":   "pd",   // default is past day for news
  "country":     "US"
}

返回：标题、来源出版物、日期、摘要、URL。

---

search_shopping

{
  "query":       "Sony WH-1000XM5 headphones",
  "num_results": 8,
  "country":     "US"
}

返回：商品名称、价格、卖家、星级评分和评论数、配送信息、商品 URL。

---

search_places ⭐ 此服务独有

{
  "query":       "ramen restaurants in Shibuya Tokyo",
  "num_results": 5,
  "country":     "JP"
}

返回：商家名称、类别、地址、电话、网站、星级评分和评论数、营业时间、GPS 坐标和 Google Maps 链接。

示例用例：

• “查找时代广场附近评分最高的咖啡店”
• “德克萨斯州奥斯汀市有哪些周日营业的牙医？”
• “列出达卡的共享办公空间”

---

search_scholar 🆕 v4.0.0

搜索 Google Scholar 中的学术文献。

{
  "query":       "attention is all you need",
  "num_results": 10,
  "country":     "US"
}

返回：标题、链接、作者／期刊／年份（publicationInfo）、摘要和引用次数。

---

scrape 🆕 v4.0.0

获取单个 URL 的完整内容（Serper Scrape API — scrape.serper.dev）。

{
  "url":              "https://example.com/article",  // required
  "include_markdown": true,       // default true — markdown rendering
  "include_images":   false,
  "include_links":    false,
  "include_videos":   false,
  "max_chars":        50000       // 1000–200000, default 50000
}

以 Markdown 格式返回页面内容（无法获取时回退为纯文本），并截断内容以确保上下文安全。每个页面约消耗 2 个积分——典型流程为 search_web → 对最佳结果执行 scrape。

---

search_many 🆕 v4.0.0

一次调用并行执行 1–10 次网页搜索。

{
  "queries":     ["react server components", "vue server components", "sveltekit ssr"],
  "num_results": 5,
  "country":     "US"
}

自动移除不同查询中的重复 URL；单个查询失败时会在结果中内联报告，不会导致整个批次失败。每个查询消耗 1 个积分。

---

环境变量

搜索提供商与通用网关

变量	必填	默认值	描述
SERPER_API_KEY	✅	—	主要搜索提供商密钥（serper.dev — 每月 2,500 次免费查询）
TAVILY_API_KEY	❌	—	Tavily 备用提供商密钥（tavily.com — AI 重新排序的搜索）
BRAVE_API_KEY	❌	—	Brave Search 备用提供商密钥（brave.com/search/api — 独立索引）
EXA_API_KEY	❌	—	Exa 神经搜索备用密钥（exa.ai — 语义搜索与摘要）
FIRECRAWL_API_KEY	❌	—	Firecrawl JS 渲染抓取与搜索升级密钥（firecrawl.dev）
SEARCH_PROVIDER_ORDER	❌	serper,tavily,brave	以逗号分隔的故障转移优先级链（serper,tavily,brave,exa,firecrawl）
SEARCH_FALLBACK	❌	true	在 402/429/5xx/空响应时自动故障转移（true 或 false）

服务与传输

变量	必填	默认值	描述
SERPER_MCP_TRANSPORT	❌	stdio	MCP 传输模式：stdio（本地 AI 客户端）或 http（无状态 Streamable HTTP）
SERPER_MCP_PORT	❌	8080	HTTP 传输模式的端口（1–65535）
SERPER_MCP_HOST	❌	0.0.0.0	HTTP 模式绑定的主机接口
SERPER_MCP_AUTH_TOKEN	❌	—	设置后，HTTP /mcp 需要 Authorization: Bearer <token>
SERPER_MCP_LOG_LEVEL	❌	info	日志详细程度：error · warn · info · debug · silent

缓存与韧性调优

变量	必填	默认值	描述
SERPER_CACHE_TTL_MS	❌	600000	搜索结果缓存 TTL，单位为 ms（0 表示禁用缓存）
SERPER_CACHE_MAX	❌	200	最大缓存响应数（LRU 淘汰）
SERPER_TIMEOUT_MS	❌	30000	Serper 调用的单次请求超时时间，单位为 ms
SERPER_RETRIES	❌	2	遇到 429 / 5xx / 网络错误时的重试次数（遵循 Retry-After）
SERPER_RETRY_BASE_MS	❌	500	基础退避延迟，单位为 ms（指数退避 + 抖动）

深度研究大模型综合

变量	必填	默认值	描述
OPENROUTER_API_KEY	❌	—	用于 deep_research 综合的 LLM 密钥（openrouter.ai 提供免费套餐）
OPENROUTER_MODEL	❌	google/gemini-3.1-flash-lite:free	OpenRouter 模型覆盖项
GEMINI_API_KEY	❌	—	用于 deep_research 综合的 LLM 密钥（ai.google.dev 提供免费套餐）
GEMINI_MODEL	❌	gemini-3.1-flash-lite	Gemini 模型覆盖项
SERPER_LLM_TIMEOUT_MS	❌	120000	LLM 综合调用的单次请求超时时间，单位为 ms
SERPER_LLM_RETRIES	❌	2	LLM 调用遇到速率限制或网络错误时的重试次数

---

HTTP 传输（远程 / Docker）

以无状态 Streamable HTTP 服务运行（Docker 镜像也以此方式运行）：

npx serper-search-mcp --transport http --port 8080
# or via env: SERPER_MCP_TRANSPORT=http SERPER_MCP_PORT=8080 npx serper-search-mcp

• MCP 端点：POST http://localhost:8080/mcp
• 健康检查：GET http://localhost:8080/health

将任何支持 Streamable HTTP 的 MCP 客户端指向 http://<host>:8080/mcp。

可选的 Bearer 身份验证

设置 SERPER_MCP_AUTH_TOKEN（或 --auth-token）以要求访问 /mcp 时进行身份验证：

SERPER_MCP_AUTH_TOKEN=secret npx serper-search-mcp --transport http --port 8080

curl -X POST http://localhost:8080/mcp \
  -H "Authorization: Bearer secret" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

未携带令牌的请求会收到 401。/health 无需身份验证，供负载均衡器使用，并会报告 auth_required。

---

示例提示词

连接到任意 MCP 客户端后：

Search for the latest news about Claude 4 and summarize the key points.

Find me 5 Italian restaurants in Warsaw with their ratings and phone numbers.

What is the current price of the MacBook Pro M4 on Google Shopping?

Search for YouTube tutorials on building agentic AI systems published this month.

Find images of brutalist architecture in Eastern Europe.

---

---

deep_research

使用你自己的 LLM 密钥执行多步 AI 研究。LLM 数据不会离开你的环境。

需要： OPENROUTER_API_KEY（openrouter.ai 上的免费模型）或 GEMINI_API_KEY（在 aistudio.google.com 上免费）

{
  "query": "What are the real-world limitations of RAG systems in production?",
  "depth": "standard",  // "basic" | "standard" | "deep"
  "country": "US"
}

深度	子查询数	每个子查询的结果数	最适合
basic	3	3	快速概览
standard	5	5	大多数使用场景
deep	8	7	全面研究

输出： 结构化 Markdown 报告，包含行内引用和来源部分。

通过环境变量支持的 LLM（所有变量均记录在上表中）：

提供方	变量	默认值
OpenRouter	OPENROUTER_API_KEY	—
	OPENROUTER_MODEL	google/gemini-3.1-flash-lite:free
Google Gemini	GEMINI_API_KEY	—
	GEMINI_MODEL	gemini-3.1-flash-lite

---

search_rag_context

将 Google 搜索结果转换为适合生成嵌入的文本块。无需 LLM——纯文本处理。

{
  "query":           "transformer architecture explained",
  "num_results":     10,
  "max_chunk_words": 200,
  "include_paa":     true,
  "output_format":   "json"   // "json" or "text"
}

JSON 输出（用于向量数据库写入）：

{
  "query": "transformer architecture explained",
  "total_sources": 10,
  "total_chunks": 24,
  "total_words": 4231,
  "chunks": [
    {
      "chunk_index": 0,
      "source_index": 1,
      "title": "Attention Is All You Need",
      "url": "https://arxiv.org/abs/1706.03762",
      "domain": "arxiv.org",
      "date": "2024-01-15",
      "text": "The transformer architecture uses self-attention mechanisms...",
      "word_count": 198,
      "char_count": 1124
    }
  ]
}

文本输出（用于直接注入提示词）：

--- Chunk 1 | Source 1 | arxiv.org | 2024-01-15 ---
Title: Attention Is All You Need
URL: https://arxiv.org/abs/1706.03762
The transformer architecture uses self-attention...

使用场景：

• 输入到 Chroma、Pinecone、Qdrant、pgvector
• 使用最新网络数据为提示词提供依据
• 构建搜索增强型 RAG 工作流

---

架构

serper-search-mcp-server/
├── index.js                    ← Zero-build JS entry (npx / Docker) — generated from src/ via `npm run bundle`; never edit by hand
├── src/
│   ├── index.ts                ← TypeScript CLI entry
│   ├── api/
│   │   ├── SerperAPI.ts        ← HTTP client (per-type endpoints, retry, timeout, TTL cache, scrape)
│   │   └── LLMClient.ts        ← OpenRouter + Gemini client
│   ├── server/
│   │   └── SerperMCPServer.ts  ← MCP server, stdio + HTTP transport, bearer auth
│   ├── tools/
│   │   ├── SearchTools.ts      ← All 14 tool definitions + validation
│   │   ├── BatchSearch.ts      ← search_many (parallel + dedupe)
│   │   ├── DeepResearch.ts     ← Multi-step research orchestration
│   │   └── RAGContext.ts       ← Chunk + metadata formatter
│   ├── types/
│   │   └── index.ts            ← Full TypeScript types
│   └── utils/
│       ├── ResultFormatter.ts  ← Markdown formatting
│       ├── HttpRetry.ts        ← Timeout + retry/backoff
│       ├── TtlCache.ts         ← TTL + LRU cache
│       ├── Logger.ts           ← Leveled stderr logger (+ request-id)
│       ├── errors.ts           ← Typed error hierarchy
│       ├── Metrics.ts          ← /health counters
│       └── EnvCheck.ts         ← Boot-time env validation
├── scripts/
│   └── bundle.mjs              ← Builds index.js from src/ (`--check` mode for CI)
├── tests/                      ← node:test suite (58 tests)
└── .github/workflows/ci.yml    ← Node 18/20/22: build + bundle check + tests

双文件设计： index.js 无需任何构建步骤即可运行（适用于 npx 和 Docker），并由 src/ 生成——TS 目录树是唯一真实来源。若两者不一致，npm run check:bundle 会导致 CI 失败。

---

获取 Serper API 密钥

1. 前往 serper.dev
2. 注册（免费，无需信用卡）
3. 从控制面板复制 API 密钥
4. 每月可获得 2,500 次免费查询

---

版本演进

功能	v1.0.0	v2.0.1	v3.0.0	v4.0.0
工具总数	5	5	8	14
search（统一）	❌	❌	❌	✅ 自动调整详细程度 + 提供商故障转移
search_web	✅ 仅自然搜索结果	✅ 仅自然搜索结果	✅ + 答案框、知识图谱、PAA、相关搜索	✅
search_images	✅	✅	✅ + 尺寸、域名	✅ + 图库布局
search_videos	✅	✅	✅ + 日期字段	✅
search_news	✅	✅	✅ 格式更简洁	✅ + 默认搜索过去 1 天的内容
search_shopping	✅	✅	✅ + 配送、优惠	✅（始终返回丰富结果）
search_places	❌	❌	✅ 地址、电话、营业时间、GPS、地图链接	✅ + 完整的 7 天营业时间、路线
search_scholar	❌	❌	❌	✅ 论文 + 引用次数
search_patents	❌	❌	❌	✅ 公开信息、受让人、日期
autocomplete	❌	❌	❌	✅ 快速查询补全
scrape	❌	❌	❌	✅ 完整网页 → Markdown
search_many	❌	❌	❌	✅ 批量搜索 + 跨查询去重
deep_research	❌	❌	✅ 子查询 → 并行搜索 → LLM 报告	✅
search_rag_context	❌	❌	✅ 分块文本 + 元数据，JSON/文本输出	✅
API 端点	全部使用带 tbm 参数的 /search	全部使用带 tbm 参数的 /search	✅ 每种类型使用正确的端点	✅ + 学术搜索 + 抓取主机
答案框 / KG / PAA	❌	❌	✅ 完整提取 SERP	✅
分页	❌	❌	✅ page 参数	✅
自动更正参数	❌	❌	✅	✅
LLM 支持	❌	❌	✅ OpenRouter + Gemini（使用用户自己的密钥）	✅
无需 LLM 的 RAG 输出	❌	❌	✅ JSON + 纯文本	✅
TypeScript 类型	部分支持（大量使用 any）	部分支持（大量使用 any）	✅ 为每种结果结构提供完整类型	✅ + 学术搜索/抓取
MCP SDK 版本	^0.5.0	^0.5.0 或 ^1.0.0	^1.0.0	^1.0.0
Node 要求	>=16	>=16	>=18（原生 fetch，无需 axios）	>=18
HTTP 传输	❌	✅	✅	✅ 无状态 Streamable HTTP
HTTP bearer 身份验证	❌	❌	❌	✅ 可选
重试 + 超时	❌	❌	❌	✅ 429/5xx/网络错误
响应缓存	❌	❌	❌	✅ TTL + LRU
日志级别	❌	❌	❌	✅ error/warn/info/debug/silent
测试 + CI	❌	❌	❌	✅ node:test + GitHub Actions
Docker	❌	✅	✅	✅
npx	❌	✅	✅	✅
客户端配置	仅 Claude Desktop	Claude Desktop + 少数客户端	Claude Desktop + Cursor + Windsurf + KiloCode + n8n	✅
遥测	❌ 无	❌ 无	❌ 无（有意如此，保障隐私）	❌ 无

---

更新日志

v4.0.0 — 通用搜索网关（多提供商、14 个工具、CLI、弹性机制、测试）

• ➕ 通用多提供商网关 — 故障转移链：Serper → Tavily → Brave（+ Exa/Firecrawl），支持 provider=all 倒数排名融合
• ➕ 14 个 MCP 工具 — 包括统一的 search（智能控制令牌的自动详细程度）、search_scholar、search_patents、autocomplete、scrape、search_many
• ➕ 开发者 CLI — search、scrape、research、rag、providers、status 子命令
• ➕ search_scholar 工具 — Google Scholar，提供作者、期刊、年份和引用次数
• ➕ scrape 工具 — 通过 scrape.serper.dev 获取完整页面内容并转换为 Markdown（可安全截断）
• ➕ search_many 工具 — 并行执行 1–10 次网页搜索、跨查询 URL 去重、隔离各查询的失败
• ➕ 重试 + 超时 — 对 429/5xx/网络错误进行重试，并采用指数退避 + 抖动（遵循 Retry-After）
• ➕ 响应缓存 — 内存 TTL + LRU（设置 SERPER_CACHE_TTL_MS=0 可禁用）
• ➕ 可选 HTTP bearer 身份验证 — SERPER_MCP_AUTH_TOKEN 保护 /mcp；/health 仍保持开放
• ➕ 真实日志级别 — SERPER_MCP_LOG_LEVEL 现在可控制 error/warn/info/debug/silent
• ➕ 测试套件 + CI — 58 个 node:test 测试（无需额外依赖，包括真实 HTTP 端到端测试）+ GitHub Actions 矩阵（Node 18/20/22）
• 🔧 HTTP 传输现在可在 Node 18 上运行 — 为 MCP SDK 提供 WebCrypto 垫片（crypto.randomUUID）；Docker 基础镜像升级为 node:20-alpine
• 🔧 search_lang 现在会正确映射到 Serper 的 hl（此前会被忽略）
• 🔧 新闻结果默认采用文档所述的过去一天时效范围
• 🔧 max_chunk_words 限制在 50–1000 之间（修复零值或负值导致的挂起）
• 🔧 deep_research 中未知的 depth 会回退到 standard
• 🔧 未知工具现在返回 MethodNotFound，而不是 InternalError
• 🔧 --api-key 未提供值时不再导致启动失败
• 🔧 index.js 由 src/ 通过 esbuild 生成；npm run check:bundle 可检测偏差
• 🔧 兼容 Windows 的 npm 脚本；npm audit 报告 0 个漏洞

v3.0.0 — 地点 + 深度研究 + RAG

• ➕ search_places 工具 — 本地商家信息，包括地址、电话、营业时间和 GPS
• ➕ 网页搜索中的知识图谱提取
• ➕ 网页搜索中的答案框提取
• ➕ 网页结果中的人们也在问 + 相关搜索
• ➕ 支持分页（page 参数）
• ➕ 网页搜索中的 autocorrect 参数
• 🔧 修正各类型对应的 Serper 端点（图片/视频/新闻/购物现在使用专用端点）
• 🔧 为所有结果结构提供完整 TypeScript 类型
• ➕ deep_research 工具 — 使用大模型合成的多步骤研究（OpenRouter / Gemini）
• ➕ search_rag_context 工具 — 提供可用于嵌入的文本块及元数据（无需大模型）
• 🔧 要求 Node ≥ 18（原生 fetch）

v2.0.1

• HTTP/SSE 传输模式
• 支持 Docker Compose
• CLI 标志

v1.0.0

• 初始版本：网页、图片、视频、新闻、购物

---

贡献

欢迎提交 PR 和问题。进行较大改动前，请先创建 issue。

git clone https://github.com/smjahid012/serper-search-mcp-server.git
cd serper-search-mcp-server
npm install
export SERPER_API_KEY="your_key"
node index.js   # test immediately, no build required

---

许可证

Apache 2.0 — 详见 LICENSE

---