serper-search-scrape-mcp-server

Instructions

Implementation Reference

• src/index.ts:137-142 (registration)

  Registration of the 'google_search' tool including name, description, and input schema reference in ListTools handler
  { name: "google_search", description: "Tool to perform web searches via Serper API and retrieve rich results. It is able to retrieve organic search results, people also ask, related searches, and knowledge graph.", inputSchema: searchInputSchema, },
• src/index.ts:50-131 (schema)

  Detailed JSON input schema for 'google_search' tool defining all parameters including advanced Google search operators
  const searchInputSchema = { type: "object", properties: { q: { type: "string", description: "Search query string (e.g., 'artificial intelligence', 'climate change solutions')" }, gl: { type: "string", description: "Optional region code for search results in ISO 3166-1 alpha-2 format (e.g., 'us', 'gb', 'de')" }, hl: { type: "string", description: "Optional language code for search results in ISO 639-1 format (e.g., 'en', 'es', 'fr')" }, location: { type: "string", description: "Optional location for search results (e.g., 'SoHo, New York, United States', 'California, United States')" }, num: { type: "number", description: "Number of results to return (default: 10)" }, tbs: { type: "string", description: "Time-based search filter ('qdr:h' for past hour, 'qdr:d' for past day, 'qdr:w' for past week, 'qdr:m' for past month, 'qdr:y' for past year)" }, page: { type: "number", description: "Page number of results to return (default: 1)" }, autocorrect: { type: "boolean", description: "Whether to autocorrect spelling in query" }, // Advanced search operators site: { type: "string", description: "Limit results to specific domain (e.g., 'github.com', 'wikipedia.org')" }, filetype: { type: "string", description: "Limit to specific file types (e.g., 'pdf', 'doc', 'xls')" }, inurl: { type: "string", description: "Search for pages with word in URL (e.g., 'download', 'tutorial')" }, intitle: { type: "string", description: "Search for pages with word in title (e.g., 'review', 'how to')" }, related: { type: "string", description: "Find similar websites (e.g., 'github.com', 'stackoverflow.com')" }, cache: { type: "string", description: "View Google's cached version of a specific URL (e.g., 'example.com/page')" }, before: { type: "string", description: "Date before in YYYY-MM-DD format (e.g., '2024-01-01')" }, after: { type: "string", description: "Date after in YYYY-MM-DD format (e.g., '2023-01-01')" }, exact: { type: "string", description: "Exact phrase match (e.g., 'machine learning', 'quantum computing')" }, exclude: { type: "string", description: "Terms to exclude from search results as comma-separated string (e.g., 'spam,ads', 'beginner,basic')" }, or: { type: "string", description: "Alternative terms as comma-separated string (e.g., 'tutorial,guide,course', 'documentation,manual')" } }, required: ["q", "gl", "hl"],
• src/index.ts:173-237 (handler)

  MCP CallTool handler for 'google_search': validates params, calls searchTools.search, formats result as MCP content
  case "google_search": { const { q, gl, hl, location, num, tbs, page, autocorrect, // Advanced search parameters site, filetype, inurl, intitle, related, cache, before, after, exact, exclude, or } = request.params.arguments || {}; if (!q || !gl || !hl) { throw new Error( "Search query and region code and language are required" ); } try { const result = await searchTools.search({ q: String(q), gl: String(gl), hl: String(hl), location: location as string | undefined, num: num as number | undefined, tbs: tbs as "qdr:h" | "qdr:d" | "qdr:w" | "qdr:m" | "qdr:y" | undefined, page: page as number | undefined, autocorrect: autocorrect as boolean | undefined, // Advanced search parameters site: site as string | undefined, filetype: filetype as string | undefined, inurl: inurl as string | undefined, intitle: intitle as string | undefined, related: related as string | undefined, cache: cache as string | undefined, before: before as string | undefined, after: after as string | undefined, exact: exact as string | undefined, exclude: exclude as string | undefined, or: or as string | undefined }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], }; } catch (error) { throw new Error(`Search failed: ${error}`); } }
• src/tools/search-tool.ts:30-39 (handler)

  SerperSearchTools.search method: thin wrapper delegating to SerperClient.search for 'google_search' logic
  async search(params: ISearchParams): Promise<ISearchResult> { try { const result = await this.serperClient.search(params); return result; } catch (error) { throw new Error( `SearchTool: failed to search for "${params.q}". ${error}` ); } }
• src/services/serper-client.ts:102-135 (handler)

  Core 'google_search' implementation: constructs advanced query using buildAdvancedQuery helper and performs POST request to Serper Google search API
  async search(params: ISearchParams): Promise<ISearchResult> { try { // Build the advanced query string const queryWithOperators = this.buildAdvancedQuery(params); // Create new params object with the enhanced query const enhancedParams = { ...params, q: queryWithOperators, }; const response = await fetch(`${this.baseUrl}/search`, { method: "POST", headers: { "Content-Type": "application/json", "X-API-KEY": this.apiKey, }, body: JSON.stringify(enhancedParams), }); if (!response.ok) { const errorText = await response.text(); throw new Error( `Serper API error: ${response.status} ${response.statusText} - ${errorText}` ); } const data = (await response.json()) as ISearchResult; return data; } catch (error) { console.error("Serper search failed:", error); throw error; } }