Serper Search MCP

---

What this does

This MCP server wraps the Serper API (Google Search results) and exposes 14 tools that any MCP-compatible AI client (Claude, Cursor, Windsurf, KiloCode, n8n, etc.) can call in real time — including web, image, video, news, shopping, places, scholar, patents, autocomplete, full-page scraping, and batch search.

Tool	What you get
search ⭐	Unified search {type, provider, verbosity} — 1 schema (~700 tokens vs ~7k for all)
search_web	Organic results + Knowledge Graph + Answer Box + "People Also Ask" + Related Searches
search_images	Image URLs, thumbnails, dimensions, source pages + gallery layout + size/orientation/color/site
search_videos	Titles, channels, durations, links
search_news	Headlines, sources, dates — freshness-filtered
search_shopping	Products, prices, ratings, delivery info (always rich)
search_places	Local businesses & POIs with address, phone, full 7-day hours, GPS + Directions (always rich)
search_scholar 🆕	Academic papers with authors, journal, year, and citation counts
search_patents 🆕	Patents with publication number, assignee, inventor, dates
autocomplete 🆕	Query completions — cheap, no LLM needed
scrape 🆕	Full page content as markdown — read articles found via search
search_many 🆕	1–10 parallel web searches with automatic cross-query dedupe
deep_research	Multi-step research: auto sub-queries → parallel searches → LLM-synthesized cited report
search_rag_context	Clean chunked text with metadata for embedding pipelines & vector DBs — no LLM needed

Verbosity (token-smart, auto by default)

Mode	Who	What	Tokens
auto (default)	server picks	dev→compact, chat→standard, scholar/research→full, places/shopping/images→always rich	varies
compact	dev coding	title+URL+1-line snippet, no KG/PAA/Related	~800
standard	normal chat	KG + Answer Box + 10 organic	~4k
full	researcher	everything + citations	~5k

Credit rule: compact fetches num=5 (never fetch-10-show-3). 1 search = 1 credit, cache hit = 0, scrape ≈ 2. deep_research: basic 3cr / standard 5cr / deep 8cr.

Providers (universal gateway — auto-failover)

Provider	Cost per 1k	When to use
Serper (default)	$3-5, 2500 free/mo	Cheapest Google truth — keep first
Tavily fallback	$8-16	AI-reranked, finance/news topics
Brave fallback	$5	Independent index, private, 669ms
Exa fallback	$4-7	Neural semantic when keywords fail
Firecrawl fallback	~$3-4 eff	JS-rendered scraping & search upgrade

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

CLI (dev power-tool — 4-32x cheaper than MCP schemas)

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

Free to start: Serper gives you 2,500 free queries/month. No credit card required.

---

Quick start

🔑 Provider Keys & Universal Gateway Configuration

This server functions as a Universal Search Gateway. Only SERPER_API_KEY is required. You can add any combination of the other 4 search providers and LLM keys to enable automatic multi-provider failover, semantic search, and scraping upgrades:

Variable	Provider / Purpose	Default / Priority
SERPER_API_KEY	Serper (Google Search baseline)	Required (serper.dev)
TAVILY_API_KEY	Tavily (AI-reranked fallback)	Optional (tavily.com)
BRAVE_API_KEY	Brave (Independent web index fallback)	Optional (brave.com/search/api)
EXA_API_KEY	Exa (Neural semantic search fallback)	Optional (exa.ai)
FIRECRAWL_API_KEY	Firecrawl (JS-rendered scraping & search upgrade)	Optional (firecrawl.dev)
OPENROUTER_API_KEY	LLM for deep_research	Optional (takes priority over Gemini)
GEMINI_API_KEY	LLM for deep_research	Optional (used when OpenRouter is absent)

Failover Control:

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

---

Option 1 — npx (MCP Client Configuration)

Add this to your MCP client config file (Claude Desktop, Cursor, Windsurf, KiloCode).

🌟 Full Universal Gateway Config (All 5 Providers + Failover):

{
  "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"
      }
    }
  }
}

(You can omit any provider keys you don't use; the server automatically detects configured providers and skips unconfigured ones).

Minimal Config (Serper Only):

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

---

Option 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

For HTTP mode (remote server or cloud):

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

---

Option 3 — Shell & CLI (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 Command Prompt:

set SERPER_API_KEY=your_key
node index.js

💡 AI-powered research is free. deep_research uses Gemini's free tier by default. Set GEMINI_API_KEY above to unlock it.

---

Config file locations

Client	Config path
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 (global) or <project>/kilo.json (project)
n8n	MCP Client node → Server URL

---

Tool reference

search_web

Google web search with the full SERP breakdown.

{
  "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
}

Response includes:

• 🎯 Answer Box — direct answer when available
• 🧠 Knowledge Graph — entity info (type, description, rating, website, attributes)
• 🌐 Organic results — title, URL, snippet, sitelinks, date
• 💬 People Also Ask — up to 4 follow-up questions with answers
• 🔗 Related Searches — up to 6 suggestions

---

search_images

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

Returns: image URL, thumbnail, dimensions (width × height), source domain, source page URL.

---

search_videos

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

Returns: title, channel, duration, publish date, video URL.

---

search_news

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

Returns: headline, source publication, date, snippet, URL.

---

search_shopping

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

Returns: product name, price, seller, star rating + review count, delivery info, product URL.

---

search_places ⭐ unique to this server

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

Returns: business name, category, address, phone, website, star rating + review count, opening hours, GPS coordinates + Google Maps link.

Example use cases:

• "Find the top-rated coffee shops near Times Square"
• "What dentists are open on Sundays in Austin TX?"
• "List coworking spaces in Dhaka"

---

search_scholar 🆕 v4.0.0

Google Scholar search for academic literature.

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

Returns: title, link, authors/journal/year (publicationInfo), snippet, and citation count.

---

scrape 🆕 v4.0.0

Fetch the full contents of a single 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
}

Returns the page as markdown (falls back to plain text), truncated for context safety. Costs ~2 credits per page — typical flow is search_web → scrape the best result.

---

search_many 🆕 v4.0.0

Run 1–10 web searches in one call, in parallel.

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

Duplicate URLs across queries are removed automatically; per-query failures are reported inline without failing the batch. One credit per query.

---

Environment variables

Search Providers & Universal Gateway

Variable	Required	Default	Description
SERPER_API_KEY	✅	—	Primary search provider key (serper.dev — 2,500 free queries/mo)
TAVILY_API_KEY	❌	—	Tavily fallback provider key (tavily.com — AI-reranked search)
BRAVE_API_KEY	❌	—	Brave Search fallback provider key (brave.com/search/api — independent index)
EXA_API_KEY	❌	—	Exa neural search fallback key (exa.ai — semantic search & highlights)
FIRECRAWL_API_KEY	❌	—	Firecrawl JS-rendered scraping & search upgrade key (firecrawl.dev)
SEARCH_PROVIDER_ORDER	❌	serper,tavily,brave	Comma-separated failover priority chain (serper,tavily,brave,exa,firecrawl)
SEARCH_FALLBACK	❌	true	Auto-failover on 402/429/5xx/empty response (true or false)

Server & Transport

Variable	Required	Default	Description
SERPER_MCP_TRANSPORT	❌	stdio	MCP transport mode: stdio (local AI clients) or http (stateless Streamable HTTP)
SERPER_MCP_PORT	❌	8080	Port for HTTP transport mode (1–65535)
SERPER_MCP_HOST	❌	0.0.0.0	Host interface to bind for HTTP mode
SERPER_MCP_AUTH_TOKEN	❌	—	If set, HTTP /mcp requires Authorization: Bearer <token>
SERPER_MCP_LOG_LEVEL	❌	info	Logging verbosity: error · warn · info · debug · silent

Cache & Resilience Tuning

Variable	Required	Default	Description
SERPER_CACHE_TTL_MS	❌	600000	Search-result cache TTL in ms (0 disables the cache)
SERPER_CACHE_MAX	❌	200	Maximum cached responses (LRU eviction)
SERPER_TIMEOUT_MS	❌	30000	Per-request timeout for Serper calls in ms
SERPER_RETRIES	❌	2	Retries on 429 / 5xx / network errors (honors Retry-After)
SERPER_RETRY_BASE_MS	❌	500	Base backoff delay in ms (exponential backoff + jitter)

Deep Research LLM Synthesis

Variable	Required	Default	Description
OPENROUTER_API_KEY	❌	—	LLM key for deep_research synthesis (free tier at openrouter.ai)
OPENROUTER_MODEL	❌	google/gemini-3.1-flash-lite:free	OpenRouter model override
GEMINI_API_KEY	❌	—	LLM key for deep_research synthesis (free tier at ai.google.dev)
GEMINI_MODEL	❌	gemini-3.1-flash-lite	Gemini model override
SERPER_LLM_TIMEOUT_MS	❌	120000	Per-request timeout for LLM synthesis calls in ms
SERPER_LLM_RETRIES	❌	2	Retries for LLM calls on rate-limit or network errors

---

HTTP transport (remote / Docker)

Run as a stateless Streamable HTTP server (this is also how the Docker image runs):

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

• MCP endpoint: POST http://localhost:8080/mcp
• Health probe: GET http://localhost:8080/health

Point any Streamable HTTP capable MCP client at http://<host>:8080/mcp.

Optional bearer auth

Set SERPER_MCP_AUTH_TOKEN (or --auth-token) to require authentication on /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"}'

Requests without the token get 401. /health stays unauthenticated for load balancers and reports auth_required.

---

Example prompts

Once connected to any MCP client:

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

Runs multi-step AI research using your own LLM key. No LLM data leaves your environment.

Requires: OPENROUTER_API_KEY (free models at openrouter.ai) or GEMINI_API_KEY (free at aistudio.google.com)

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

Depth	Sub-queries	Results each	Best for
basic	3	3	Quick overviews
standard	5	5	Most use cases
deep	8	7	Exhaustive research

Output: Structured markdown report with inline citations + Sources section.

Supported LLMs via env (all vars documented in the table above):

Provider	Variable	Default
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

Turns Google search results into embedding-ready chunks. No LLM needed — pure text processing.

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

JSON output (for vector DB ingestion):

{
  "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
    }
  ]
}

Text output (for direct prompt injection):

--- 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...

Use cases:

• Feed into Chroma, Pinecone, Qdrant, pgvector
• Ground prompts with fresh web data
• Build search-augmented RAG pipelines

---

Architecture

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

Dual-file design: index.js runs without any build step (ideal for npx and Docker) and is generated from src/ — the TS tree is the only source of truth. npm run check:bundle fails CI if they drift.

---

Get a Serper API key

1. Go to serper.dev
2. Sign up (free — no credit card)
3. Copy your API key from the dashboard
4. You get 2,500 free queries/month

---

Version evolution

Feature	v1.0.0	v2.0.1	v3.0.0	v4.0.0
Total tools	5	5	8	14
search (unified)	❌	❌	❌	✅ auto-verbosity + provider failover
search_web	✅ organic only	✅ organic only	✅ + Answer Box, Knowledge Graph, PAA, Related	✅
search_images	✅	✅	✅ + dimensions, domain	✅ + gallery layout
search_videos	✅	✅	✅ + date field	✅
search_news	✅	✅	✅ cleaner formatting	✅ + past-day default
search_shopping	✅	✅	✅ + delivery, offers	✅ (always rich)
search_places	❌	❌	✅ address, phone, hours, GPS, Maps link	✅ + full 7-day hours, directions
search_scholar	❌	❌	❌	✅ papers + citation counts
search_patents	❌	❌	❌	✅ publication, assignee, dates
autocomplete	❌	❌	❌	✅ fast query completions
scrape	❌	❌	❌	✅ full page → markdown
search_many	❌	❌	❌	✅ batch + cross-query dedupe
deep_research	❌	❌	✅ sub-queries → parallel search → LLM report	✅
search_rag_context	❌	❌	✅ chunked text + metadata, JSON/text output	✅
API endpoints	all hitting /search with tbm param	all hitting /search with tbm param	✅ correct per-type endpoints	✅ + scholar + scrape host
Answer Box / KG / PAA	❌	❌	✅ full SERP extraction	✅
Pagination	❌	❌	✅ page param	✅
Autocorrect param	❌	❌	✅	✅
LLM support	❌	❌	✅ OpenRouter + Gemini (user's own key)	✅
LLM-free RAG output	❌	❌	✅ JSON + plain text	✅
TypeScript types	partial (heavy any)	partial (heavy any)	✅ full types for every result shape	✅ + scholar/scrape
MCP SDK version	^0.5.0	^0.5.0 or ^1.0.0	^1.0.0	^1.0.0
Node requirement	>=16	>=16	>=18 (native fetch, no axios)	>=18
HTTP transport	❌	✅	✅	✅ stateless Streamable HTTP
HTTP bearer auth	❌	❌	❌	✅ optional
Retry + timeout	❌	❌	❌	✅ 429/5xx/network
Response cache	❌	❌	❌	✅ TTL + LRU
Log levels	❌	❌	❌	✅ error/warn/info/debug/silent
Tests + CI	❌	❌	❌	✅ node:test + GitHub Actions
Docker	❌	✅	✅	✅
npx	❌	✅	✅	✅
Client configs	Claude Desktop only	Claude Desktop + a few	Claude Desktop + Cursor + Windsurf + KiloCode + n8n	✅
Telemetry	❌ none	❌ none	❌ none (intentional — privacy win)	❌ none

---

Changelog

v4.0.0 — Universal Search Gateway (Multi-Provider, 14 Tools, CLI, Resilience, Tests)

• ➕ Universal Multi-Provider Gateway — failover chain: Serper → Tavily → Brave (+ Exa/Firecrawl) with provider=all reciprocal-rank fusion
• ➕ 14 MCP Tools — including unified search (token-smart auto-verbosity), search_scholar, search_patents, autocomplete, scrape, search_many
• ➕ Developer CLI — search, scrape, research, rag, providers, status subcommands
• ➕ search_scholar tool — Google Scholar with authors, journal, year, citation counts
• ➕ scrape tool — full page content as markdown via scrape.serper.dev (truncation-safe)
• ➕ search_many tool — 1–10 parallel web searches, cross-query URL dedupe, per-query failure isolation
• ➕ Retry + timeout — 429/5xx/network retries with exponential backoff + jitter (Retry-After honored)
• ➕ Response cache — in-memory TTL + LRU (SERPER_CACHE_TTL_MS=0 disables)
• ➕ Optional HTTP bearer auth — SERPER_MCP_AUTH_TOKEN guards /mcp; /health stays open
• ➕ Real log levels — SERPER_MCP_LOG_LEVEL now controls error/warn/info/debug/silent
• ➕ Test suite + CI — 58 node:test tests (no extra deps, incl. real-HTTP e2e) + GitHub Actions matrix (Node 18/20/22)
• 🔧 HTTP transport now works on Node 18 — WebCrypto shim for the MCP SDK (crypto.randomUUID); Docker base image bumped to node:20-alpine
• 🔧 search_lang is now correctly mapped to Serper's hl (was previously ignored)
• 🔧 News results default to past-day freshness as documented
• 🔧 max_chunk_words clamped 50–1000 (fixes a hang on zero/negative values)
• 🔧 Unknown depth falls back to standard in deep_research
• 🔧 Unknown tools return MethodNotFound instead of InternalError
• 🔧 --api-key without a value no longer breaks startup
• 🔧 index.js is generated from src/ via esbuild; npm run check:bundle guards drift
• 🔧 Windows-compatible npm scripts; npm audit reports 0 vulnerabilities

v3.0.0 — Places + Deep Research + RAG

• ➕ search_places tool — local businesses with address, phone, hours, GPS
• ➕ Knowledge Graph extraction in web search
• ➕ Answer Box extraction in web search
• ➕ People Also Ask + Related Searches in web results
• ➕ Pagination support (page param)
• ➕ autocorrect param on web search
• 🔧 Corrected per-type Serper endpoints (images/videos/news/shopping now use dedicated endpoints)
• 🔧 Full TypeScript types for all result shapes
• ➕ deep_research tool — multi-step research with LLM synthesis (OpenRouter / Gemini)
• ➕ search_rag_context tool — embedding-ready chunks with metadata (no LLM needed)
• 🔧 Node ≥ 18 requirement (native fetch)

v2.0.1

• HTTP/SSE transport mode
• Docker Compose support
• CLI flags

v1.0.0

• Initial release: web, images, videos, news, shopping

---

Contributing

PRs and issues are welcome. Please open an issue before large changes.

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

---

License

Apache 2.0 — see LICENSE

---