serper-search-mcp-server

search_web

Search Google to retrieve organic web results plus knowledge panels, answer boxes, People Also Ask, and related queries, with freshness, country, language, and pagination filters.

Instructions

Google web search via Serper API. Returns organic results plus Knowledge Graph, Answer Box, People Also Ask, and related searches. For latest/current results pass freshness (e.g. py=past year). For a synthesized answer in one call, prefer search_rag_context (fast) or deep_research (thorough) instead of search→scrape chains.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search_web"
  }
}

Input Schema

Name	Required	Description	Default
`page`	No	Page number for pagination. Default: 1.
`query`	Yes	Search query (max 400 chars / 50 words).
`country`	No	ISO 3166-1 alpha-2 country code (e.g. "US", "GB"). Default: "US".
`ui_lang`	No	UI language (e.g. "en-US"). Default: "en".
`provider`	No	Search backend: auto (failover chain), serper, tavily, brave, exa, firecrawl. Default: auto.	auto
`freshness`	No	Time filter: pd=past day pw=week pm=month py=year any=none (historical). Pass pd/pw/pm/py whenever the user asks for latest/current/recent results ("today", "this week", "latest", current year); omit or "any" for timeless or historical questions. The response footer echoes the filter that was applied.
`max_chars`	No	Truncate response to this many characters (0 = no limit).
`verbosity`	No	Output density: auto (server picks per audience), compact (~800 tokens, dev fast path), standard (KG+Box+10), full (everything, always for places/shopping/images/scholar). Default: auto.	auto
`safesearch`	No	"off" \| "moderate" \| "strict". Default: "moderate".	moderate
`autocorrect`	No	Auto-correct spelling. Default: true.
`num_results`	No	Results (1–20, default 10). Note: >10 results uses 2 Serper credits.
`search_lang`	No	Language code (e.g. "en", "de"). Default: "en".
`snippets_only`	No	Return 1-line snippets only (token-saving for agents). Default: false.
`link_resolution`	No	Google result links beyond the top 3 may come back as google.com/goto redirects. "auto" (default): top 3 resolved, any leftover goto links get a search_id for resolve_links. "all": also resolve every link now (free, but adds ~30 s when goto links are present). "none": fastest, links exactly as Google returns them.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv4.1.0Nov 14, 2026

changedInput schema / properties / freshness / description

Previous value: -"Time filter: pd=day pw=week pm=month py=year."New value: +"Time filter: pd=past day pw=week pm=month py=year any=none (historical). Pass pd/pw/pm/py whenever the user asks for latest/current/recent results (\"today\", \"this week\", \"latest\", current year); omit or \"any\" for timeless or historical questions. The response footer echoes the filter that was applied."

changedInput schema / properties / freshness / enum

Previous value: -[
-  "pd",
-  "pw",
-  "pm",
-  "py"
-]New value: +[
+  "pd",
+  "pw",
+  "pm",
+  "py",
+  "any"
+]

removedInput schema / properties / summary

Removed value: -{
-  "default": false,
-  "description": "Request Serper AI summary. Default: false.",
-  "type": "boolean"
-}

First observedv4.0.1Nov 12, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are supplied, so the description carries the full burden, and it does disclose the response composition, which is important given there is no output schema. It does not mention auth requirements, rate limits, per-provider credit costs, or failure behavior of the 'auto' failover chain, so the behavioral picture is good but not complete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tightly-packed sentences with zero filler: capability and return shape first, then recency handling, then alternative-tool routing. Front-loading is correct and each sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter, no-output-schema, no-annotation tool, the description covers purpose, return contents, recency handling, and sibling routing. Remaining gaps (provider failover semantics, verbosity tradeoffs, link-resolution latency) are documented in the schema, so the description is nearly sufficient without bloating.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every parameter, including enum meanings for freshness, verbosity, link_resolution, and safesearch, is already documented in the schema. The description adds only usage framing for freshness (when to pass pd/pw/pm/py), which is largely duplicative of the schema text, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Google web search via Serper API') and enumerates the result payload (organic results, Knowledge Graph, Answer Box, People Also Ask, related searches). This distinguishes it from synthesis-oriented siblings like search_rag_context and deep_research, which are named directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use guidance ('For latest/current results pass freshness, e.g. py=past year') and an explicit when-not-to-use with named alternatives ('prefer search_rag_context (fast) or deep_research (thorough) instead of search→scrape chains'). The anti-pattern warning against chaining search into scrape is exactly the routing signal an agent needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server