Serper Search and Scrape MCP Server

Instructions

Implementation Reference

• src/services/serper-client.ts:102-135 (handler)

  Core handler that executes the Google search by making HTTP POST request to Serper API. Builds advanced query with operators, sends authenticated request, and returns search results.

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

• src/index.ts:173-237 (handler)

  MCP request handler for 'google_search' tool. Extracts parameters from request, validates required fields (q, gl, hl), calls searchTools.search(), and returns formatted JSON response.

  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/index.ts:50-132 (schema)

  Input schema definition for google_search tool with 17 properties including basic parameters (q, gl, hl, location, num, tbs, page, autocorrect) and advanced search operators (site, filetype, inurl, intitle, related, cache, before, after, exact, exclude, or).

  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:136-142 (registration)

  Tool registration defining 'google_search' with description 'Tool to perform web searches via Serper API and retrieve rich results' and referencing the input schema.

  tools: [
    {
      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/services/serper-client.ts:42-100 (helper)

  Helper method that builds advanced Google search query strings by combining base query with operators like site:, filetype:, inurl:, intitle:, before:, after:, and OR logic.

  private buildAdvancedQuery(params: ISearchParams): string {
    // Normalize spaces in the query
    let query = params.q.trim().replace(/\s+/g, ' ');
  
    // Add site restriction
    if (params.site) {
      query += ` site:${params.site}`;
    }
  
    // Add file type filter
    if (params.filetype) {
      query += ` filetype:${params.filetype}`;
    }
  
    // Add URL word search
    if (params.inurl) {
      query += ` inurl:${params.inurl}`;
    }
  
    // Add title word search
    if (params.intitle) {
      query += ` intitle:${params.intitle}`;
    }
  
    // Add related sites search
    if (params.related) {
      query += ` related:${params.related}`;
    }
  
    // Add cached page view
    if (params.cache) {
      query += ` cache:${params.cache}`;
    }
  
    // Add date range filters
    if (params.before) {
      query += ` before:${params.before}`;
    }
    if (params.after) {
      query += ` after:${params.after}`;
    }
  
    // Add exact phrase match
    if (params.exact) {
      query += ` "${params.exact}"`;
    }
  
    // Add excluded terms
    if (params.exclude) {
      query += params.exclude.split(',').map(term => ` -${term.trim()}`).join('');
    }
  
    // Add OR terms
    if (params.or) {
      query += ` (${params.or.split(',').map(term => term.trim()).join(' OR ')})`;
    }
  
    return query.trim();
  }