🔍 Serper Search MCP Server v4.0

The First Universal Search Gateway for AI Agents — Google (Serper), Tavily, Brave, Exa, and Firecrawl with auto-failover, 14 tools, and token-smart verbosity.

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.

Verbosity (token-smart, auto by default)

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)

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.

Related MCP server: Argus

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:

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

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
  "link_resolution": "auto" // "auto" · "all" · "none" — see Google redirect links below
}

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.

Google redirect links & resolve_links 🆕

Since 2026-10-30, Serper may return Google result links beyond the top 3 as https://www.google.com/goto?url=… redirects. Opening one right after the search lands on Google's "Verifying your request" page instead of the site. Serper's free /resolve endpoint turns them back into real URLs (serper.dev/google-links).

search, search_web, search_images, search_videos, search_news, search_shopping and search_rag_context take a link_resolution parameter:

resolve_links resolves a search later by search_id (the last 50 searches with redirect links are kept in memory) or from a list of goto links:

{ "search_id": "Xq3v…" }                                 // re-renders that search with real URLs
{ "links": ["https://www.google.com/goto?url=…"], "max_wait_seconds": 60 }

Links that are not ready yet stay goto links and Serper suggests a wait (often 90 s); it is honoured only if it fits in max_wait_seconds. /resolve failures never fail a search: the original results are kept and the error is shown. deep_research resolves its sources before building the prompt and lists any citation that is still a redirect.

Environment variables

Search Providers & Universal Gateway

Server & Transport

Cache & Resilience Tuning

Deep Research LLM Synthesis

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

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

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

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 15 tool definitions + validation
│   │   ├── BatchSearch.ts      ← search_many (parallel + dedupe)
│   │   ├── DeepResearch.ts     ← Multi-step research orchestration
│   │   ├── RAGContext.ts       ← Chunk + metadata formatter
│   │   └── ResolveLinks.ts     ← link_resolution modes + resolve_links (Serper /resolve)
│   ├── 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

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

Built by SMLabs AI · smjahid012
If this saved you time, a ⭐ on GitHub helps others find it.