Serper MCP Server

Instructions

Implementation Reference

• src/serper_mcp_server/server.py:62-81 (handler)

  MCP server handler for all tools, including google_search_patents. Parses arguments into PatentsRequest schema, calls core google(tool, request) which proxies to Serper Patents API, and returns JSON results.

  @server.call_tool()
  async def call_tool(name: str, arguments: dict[str, Any]) -> Sequence[TextContent | ImageContent | EmbeddedResource]:
      if not SERPER_API_KEY:
          return [TextContent(text=f"SERPER_API_KEY is empty!", type="text")]
  
      try:
          if name == SerperTools.WEBPAGE_SCRAPE.value:
              request = WebpageRequest(**arguments)
              result = await scape(request)
              return [TextContent(text=json.dumps(result, indent=2), type="text")]
  
          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")]
      except Exception as e:
          return [TextContent(text=f"Error: {str(e)}", type="text")]

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

  Executes the tool logic for google_search_patents by deriving the '/patents' endpoint from the tool name, serializing the request to JSON payload, authenticating with SERPER_API_KEY, and POSTing to https://google.serper.dev/patents via aiohttp.

  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)
  
  
  async def scape(request: WebpageRequest) -> Dict[str, Any]:
      url = "https://scrape.serper.dev"
      return await fetch_json(url, request)
  
  
  async def fetch_json(url: str, request: BaseModel) -> Dict[str, Any]:
      payload = request.model_dump(exclude_none=True)
      headers = {
          'X-API-KEY': SERPER_API_KEY,
          'Content-Type': 'application/json'
      }
  
      ssl_context = ssl.create_default_context(cafile=certifi.where())
      connector = aiohttp.TCPConnector(ssl=ssl_context)
  
      timeout = aiohttp.ClientTimeout(total=AIOHTTP_TIMEOUT)
      async with aiohttp.ClientSession(connector=connector, timeout=timeout) as session:
          async with session.post(url, headers=headers, json=payload) as response:
              response.raise_for_status()
              return await response.json()

• src/serper_mcp_server/schemas.py:104-116 (schema)

  Pydantic input schema/validation for google_search_patents tool parameters: query (required), num results (default 10, max 100), page (default 1).

  class PatentsRequest(BaseModel):
      q: str = Field(..., description="The query to search for")
      num: str = Field(
          "10",
          pattern=r"^([1-9]|[1-9]\d|100)$",
          description="The number of results to return, max is 100 (integer value as string)",
      )
      page: Optional[str] = Field(
          "1",
          pattern=r"^[1-9]\d*$",
          description="The page number to return, first page is 1 (integer value as string)",
      )

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

  Registers the google_search_patents tool with the MCP server using @server.list_tools(), deriving name from enum value and inputSchema from PatentsRequest via google_request_map.

  @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:25-38 (registration)

  Maps SerperTools.GOOGLE_SEARCH_PATENTS enum to PatentsRequest schema for use in tool registration and dispatching.

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