Serper MCP Server

Instructions

Implementation Reference

• src/serper_mcp_server/core.py:14-18 (handler)

  Handler function that executes the google_search_reviews tool logic by constructing the Serper API URL (/reviews) from the tool name and delegating to fetch_json for the HTTP POST request.

  async def google(tool: SerperTools, request: BaseModel) -> Dict[str, Any]:
      uri_path = tool.value.split("_")[-1]
      url = f"https://google.serper.dev/{uri_path}"
      return await fetch_json(url, request)

• src/serper_mcp_server/schemas.py:62-79 (schema)

  Pydantic schema for input validation of google_search_reviews tool parameters.

  class ReviewsRequest(BaseModel):
      fid: str = Field(..., description="The FID")
      cid: Optional[str] = Field(None, description="The CID to search in")
      placeId: Optional[str] = Field(None, description="The place ID to search in")
      sortBy: Optional[str] = Field(
          "mostRelevant",
          pattern=r"^(mostRelevant|newest|highestRating|lowestRating)$",
          description="The sort order to use (enum value as string: 'mostRelevant', 'newest', 'highestRating', 'lowestRating')",
      )
      topicId: Optional[str] = Field(None, description="The topic ID to search in")
      nextPageToken: Optional[str] = Field(None, description="The next page token to use")
      gl: Optional[str] = Field(
          None, description="The country to search in, e.g. us, uk, ca, au, etc."
      )
      hl: Optional[str] = Field(
          None, description="The language to search in, e.g. en, es, fr, de, etc."
      )

• src/serper_mcp_server/server.py:25-38 (registration)

  Maps SerperTools enum values to input schema classes; maps GOOGLE_SEARCH_REVIEWS to ReviewsRequest for tool dispatch.

  google_request_map = {
      SerperTools.GOOGLE_SEARCH: SearchRequest,
      SerperTools.GOOGLE_SEARCH_IMAGES: SearchRequest,
      SerperTools.GOOGLE_SEARCH_VIDEOS: SearchRequest,
      SerperTools.GOOGLE_SEARCH_PLACES: AutocorrectRequest,
      SerperTools.GOOGLE_SEARCH_MAPS: MapsRequest,
      SerperTools.GOOGLE_SEARCH_REVIEWS: ReviewsRequest,
      SerperTools.GOOGLE_SEARCH_NEWS: SearchRequest,
      SerperTools.GOOGLE_SEARCH_SHOPPING: ShoppingRequest,
      SerperTools.GOOGLE_SEARCH_LENS: LensRequest,
      SerperTools.GOOGLE_SEARCH_SCHOLAR: AutocorrectRequest,
      SerperTools.GOOGLE_SEARCH_PATENTS: PatentsRequest,
      SerperTools.GOOGLE_SEARCH_AUTOCOMPLETE: AutocorrectRequest,
  }

• src/serper_mcp_server/server.py:41-60 (registration)

  Registers the google_search_reviews tool (via google_request_map) with MCP server, providing name, description, and input schema.

  @server.list_tools()
  async def list_tools() -> List[Tool]:
      tools = []
  
      for k, v in google_request_map.items():
          tools.append(
              Tool(
                  name=k.value,
                  description="Search Google for results",
                  inputSchema=v.model_json_schema(),
              ),
          )
  
      tools.append(Tool(
          name=SerperTools.WEBPAGE_SCRAPE,
          description="Scrape webpage by url",
          inputSchema=WebpageRequest.model_json_schema(),
      ))
  
      return tools

• src/serper_mcp_server/server.py:73-79 (handler)

  Dispatch logic in the main call_tool handler that routes google_search_reviews calls to the appropriate schema and google handler.

  if not SerperTools.has_value(name):
      raise ValueError(f"Tool {name} not found")
  
  tool = SerperTools(name)
  request = google_request_map[tool](**arguments)
  result = await google(tool, request)
  return [TextContent(text=json.dumps(result, indent=2), type="text")]