What this does

This MCP server wraps the Serper API (Google Search results) and exposes 8 search tools that any MCP-compatible AI client (Claude, Cursor, Windsurf, KiloCode, n8n, etc.) can call in real time.

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

Quick start

Option 1 — npx (zero install)

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

Add this to your MCP client config (paths listed below), then restart.

Option 2 — Docker

{
  "mcpServers": {
    "serper-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "SERPER_API_KEY", "-e", "GEMINI_API_KEY", "smjahid/server-serper-search:3"],
      "env": {
        "SERPER_API_KEY": "your_key_here",
        "GEMINI_API_KEY": "your_gemini_key_here"
      }
    }
  }
}

Or run directly:

docker run -i --rm \
  -e SERPER_API_KEY=your_key \
  -e GEMINI_API_KEY=your_gemini_key \
  smjahid/server-serper-search:3

Option 3 — Local clone

git clone https://github.com/smjahid012/serper-search-mcp-server.git
cd serper-search-mcp-server
npm install
export SERPER_API_KEY="your_key"
export GEMINI_API_KEY="your_gemini_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
}

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"

Environment variables

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)
└── src/
    ├── index.ts                ← TypeScript CLI entry
    ├── api/
    │   ├── SerperAPI.ts        ← HTTP client (per-type endpoints)
    │   └── LLMClient.ts        ← OpenRouter + Gemini client
    ├── server/
    │   └── SerperMCPServer.ts  ← MCP Server + tool routing
    ├── tools/
    │   ├── SearchTools.ts      ← All 8 tool definitions + validation
    │   ├── DeepResearch.ts     ← Multi-step research orchestration
    │   └── RAGContext.ts       ← Chunk + metadata formatter
    ├── types/
    │   └── index.ts            ← Full TypeScript types
    └── utils/
        └── ResultFormatter.ts  ← Markdown formatting

Dual-file design: index.js runs without any build step (ideal for npx and Docker). The TypeScript src/ tree is for contributors who want type safety and IDE support.

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

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