Enhanced Google Search MCP

Instructions

Implementation Reference

• src/search.ts:447-735 (handler)

  Core implementation of the search tool: performs anonymized Google web search with retries, DNS rotation, request fingerprinting, and robust result parsing using multiple strategies.
  export async function performSearch( query: string, options: SearchOptions = {} ): Promise<SearchResult[]> { const limit = Math.min(options.limit || 5, 10); // Test and find working DNS before starting search console.log("Testing DNS resolution..."); await DNSResolver.findWorkingDNS("google.com"); // Create axios instance with enhanced configuration const axiosInstance = axios.create({ maxRedirects: 3, timeout: 12000, validateStatus: (status) => status < 500, // Accept 4xx errors but retry on 5xx // DNS optimization for better reliability family: 4, // Force IPv4 to avoid IPv6 DNS issues // Use HTTPS agent with DNS optimization httpsAgent: new Agent({ family: 4, keepAlive: true, keepAliveMsecs: 1000, maxSockets: 5, maxFreeSockets: 2, timeout: 10000, }), }); // Configure enhanced retry logic with adaptive strategies axiosRetry(axiosInstance, { onRetry: async (retryCount, error, requestConfig) => { console.log(`Retry attempt ${retryCount} for ${requestConfig.url}`); // Rotate DNS on network errors or DNS-related failures if (error.code === 'ENOTFOUND' || error.code === 'EAI_AGAIN' || retryCount > 2) { console.log(`DNS-related error detected, rotating DNS server...`); DNSResolver.rotateDNS(); await DNSResolver.testDNSResolution("google.com"); } // Rotate user agent on retry to avoid detection if (retryCount > 1) { let newUserAgent = randomUseragent.getRandom(); // Try to get a desktop user agent for (let i = 0; i < 3; i++) { if (newUserAgent && (newUserAgent.includes('Windows') || newUserAgent.includes('Macintosh') || newUserAgent.includes('Linux'))) { break; } newUserAgent = randomUseragent.getRandom(); } requestConfig.headers = { ...requestConfig.headers, ...RequestAnonymizer.generateHeaders(newUserAgent) }; console.log(`Rotated user agent for retry ${retryCount}: ${newUserAgent.substring(0, 50)}...`); } }, retries: 8, retryCondition: (error) => { // Network errors - always retry if (axiosRetry.isNetworkError(error)) { return true; } // Idempotent request errors - always retry if (axiosRetry.isIdempotentRequestError(error)) { return true; } // HTTP status based retries if (error.response?.status) { const status = error.response.status; // Server errors (5xx) - always retry if (status >= 500) { return true; } // Rate limiting (429) - retry with longer delays if (status === 429) { return true; } // Temporary redirects that might resolve if (status === 302 || status === 307 || status === 308) { return true; } // Request timeout - retry if (status === 408) { return true; } // Too many requests from this IP - retry with longer delay if (status === 503) { return true; } } // Timeout errors - retry if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT') { return true; } // DNS resolution errors - retry if (error.code === 'ENOTFOUND' || error.code === 'EAI_AGAIN') { return true; } // Connection errors - retry if (error.code === 'ECONNRESET' || error.code === 'ECONNREFUSED') { return true; } return false; }, retryDelay: (retryCount, error) => { // Adaptive delay based on error type let baseDelay = Math.pow(2, retryCount) * 1000; // Exponential backoff // Longer delays for rate limiting if (error?.response?.status === 429) { baseDelay = Math.pow(3, retryCount) * 2000; // More aggressive backoff for rate limits } // Shorter delays for network errors if (axiosRetry.isNetworkError(error)) { baseDelay = Math.min(baseDelay, 3000); // Cap network error delays } // Add jitter to prevent thundering herd const jitter = Math.random() * Math.min(1000, baseDelay * 0.3); const totalDelay = baseDelay + jitter; console.log(`Retry ${retryCount}: waiting ${totalDelay}ms (error: ${error?.response?.status || error?.code || 'unknown'})`); return totalDelay; }, }); // Generate realistic request fingerprint using random-useragent library // Try to get a desktop user agent, fallback to any if none found let userAgent = randomUseragent.getRandom(); // If we got a mobile user agent, try a few more times to get a desktop one for (let i = 0; i < 5; i++) { if (userAgent && (userAgent.includes('Windows') || userAgent.includes('Macintosh') || userAgent.includes('Linux'))) { break; } userAgent = randomUseragent.getRandom(); } let headers = RequestAnonymizer.generateHeaders(userAgent); let params = SearchParameterBuilder.build(query, options); // Add random delay to avoid detection await RequestAnonymizer.addRandomDelay(); // Multiple attempt strategy with different approaches const maxAttempts = 5; let lastError: Error | null = null; for (let attempt = 1; attempt <= maxAttempts; attempt++) { try { console.log(`Search attempt ${attempt}/${maxAttempts} for query: "${query}"`); // Update params for this attempt params = SearchParameterBuilder.build(query, options, attempt); const config: AxiosRequestConfig = { decompress: true, headers, params, // Increase timeout for later attempts timeout: 12000 + (attempt - 1) * 3000, }; const response = await axiosInstance.get("https://www.google.com/search", config); // Validate response if (response.status === 429) { const retryAfter = response.headers['retry-after']; const waitTime = retryAfter ? parseInt(retryAfter) * 1000 : 5000; console.log(`Rate limited, waiting ${waitTime}ms before next attempt`); await new Promise(resolve => setTimeout(resolve, waitTime)); if (attempt === maxAttempts) { throw new Error("Rate limited by Google. Please try again later."); } continue; } if (response.status >= 400) { if (attempt === maxAttempts) { throw new Error(`Google search failed with status ${response.status}`); } console.log(`HTTP ${response.status} on attempt ${attempt}, retrying...`); await RequestAnonymizer.addRandomDelay(); continue; } // Check if we got a valid response if (!response.data || response.data.length < 1000) { if (attempt === maxAttempts) { throw new Error("Received invalid or empty response from Google"); } console.log(`Invalid response on attempt ${attempt}, retrying...`); await RequestAnonymizer.addRandomDelay(); continue; } const results = ResultParser.parse(response.data, limit); // If we got results, return them if (results.length > 0) { console.log(`Successfully found ${results.length} results on attempt ${attempt}`); return results; } // If no results and this is not the last attempt, try again if (attempt < maxAttempts) { console.log(`No results found on attempt ${attempt}, retrying with different strategy...`); // Rotate user agent for next attempt let newUserAgent = randomUseragent.getRandom(); for (let i = 0; i < 3; i++) { if (newUserAgent && (newUserAgent.includes('Windows') || newUserAgent.includes('Macintosh') || newUserAgent.includes('Linux'))) { break; } newUserAgent = randomUseragent.getRandom(); } headers = RequestAnonymizer.generateHeaders(newUserAgent); await RequestAnonymizer.addRandomDelay(); continue; } // Last attempt and no results return results; } catch (error) { lastError = error instanceof Error ? error : new Error(String(error)); console.log(`Attempt ${attempt} failed:`, lastError.message); if (attempt === maxAttempts) { break; } // Wait before next attempt with shorter delays for more aggressive retries const waitTime = Math.min(1000 * attempt, 5000); console.log(`Waiting ${waitTime}ms before next attempt...`); await new Promise(resolve => setTimeout(resolve, waitTime)); // Rotate user agent for next attempt let newUserAgent = randomUseragent.getRandom(); for (let i = 0; i < 3; i++) { if (newUserAgent && (newUserAgent.includes('Windows') || newUserAgent.includes('Macintosh') || newUserAgent.includes('Linux'))) { break; } newUserAgent = randomUseragent.getRandom(); } headers = RequestAnonymizer.generateHeaders(newUserAgent); } } // All attempts failed, throw the last error with enhanced message if (lastError) { if (axios.isAxiosError(lastError)) { if (lastError.code === "ECONNABORTED" || lastError.code === "ETIMEDOUT") { throw new Error("Search request timed out after multiple attempts. Please check your internet connection and try again."); } if (lastError.response?.status === 403) { throw new Error("Access denied by Google after multiple attempts. The requests may have been blocked. Please try again later."); } if (lastError.response?.status === 429) { throw new Error("Rate limited by Google after multiple attempts. Please try again in a few minutes."); } if (lastError.response?.status === 503) { throw new Error("Google service temporarily unavailable. Please try again later."); } } throw new Error(`Search failed after ${maxAttempts} attempts: ${lastError.message}`); } throw new Error(`Search failed after ${maxAttempts} attempts: Unknown error`); }
• src/server.ts:56-120 (handler)

  MCP tool handler wrapper: processes arguments, calls performSearch, formats results, provides logging and user-friendly error messages.
  execute: async (args, { log }) => { try { log.info("Starting enhanced web search", { query: args.query, limit: args.limit, options: { language: args.language, region: args.region, safeSearch: args.safeSearch, timeRange: args.timeRange, }, }); const searchOptions: SearchOptions = { limit: args.limit, language: args.language, region: args.region, safeSearch: args.safeSearch, timeRange: args.timeRange, }; const results = await performSearch(args.query, searchOptions); log.info("Search completed successfully", { resultCount: results.length, query: args.query, }); if (results.length === 0) { return "No search results found. This could be due to:\n" + "- Very specific or uncommon search terms\n" + "- Temporary blocking by Google (try again later)\n" + "- Network connectivity issues\n" + "- Search filters being too restrictive"; } // Format results in a readable way const formattedResults = results.map((result, index) => { return `${index + 1}. **${result.title}**\n` + ` URL: ${result.url}\n` + ` Description: ${result.description || "No description available"}\n`; }).join("\n"); return `Found ${results.length} search results for "${args.query}":\n\n${formattedResults}`; } catch (error) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; log.error("Search failed", { query: args.query, error: errorMessage, }); // Provide helpful error messages to users if (errorMessage.includes("Rate limited")) { return `Search temporarily unavailable due to rate limiting. Please try again in a few minutes.\n\nQuery: "${args.query}"`; } else if (errorMessage.includes("Access denied") || errorMessage.includes("blocked")) { return `Search request was blocked by Google. This can happen with frequent requests. Please try again later.\n\nQuery: "${args.query}"`; } else if (errorMessage.includes("timeout")) { return `Search request timed out. Please check your internet connection and try again.\n\nQuery: "${args.query}"`; } else { return `Search failed: ${errorMessage}\n\nQuery: "${args.query}"\n\nTip: Try rephrasing your search query or try again later.`; } } },
• src/server.ts:25-50 (schema)

  Zod input schema defining parameters for the search tool: query (required), limit, language, region, safeSearch, timeRange.
  parameters: z.object({ query: z.string().describe("Search query to execute"), limit: z .number() .min(1) .max(10) .optional() .default(5) .describe("Maximum number of results to return (1-10, default: 5)"), language: z .string() .optional() .describe("Language code for results (e.g., 'en', 'es', 'fr', 'de', 'ja')"), region: z .string() .optional() .describe("Region code for localized results (e.g., 'us', 'uk', 'ca', 'au')"), safeSearch: z .enum(["off", "moderate", "strict"]) .optional() .describe("Safe search filter level"), timeRange: z .enum(["hour", "day", "week", "month", "year"]) .optional() .describe("Time range filter for recent results"), }),
• src/server.ts:22-121 (registration)

  Registration of the 'search' tool object with FastMCP server.addTool method.
  server.addTool({ name: "search", description: "Search the web using Google with enhanced anonymization and anti-detection features. Supports advanced filtering options.", parameters: z.object({ query: z.string().describe("Search query to execute"), limit: z .number() .min(1) .max(10) .optional() .default(5) .describe("Maximum number of results to return (1-10, default: 5)"), language: z .string() .optional() .describe("Language code for results (e.g., 'en', 'es', 'fr', 'de', 'ja')"), region: z .string() .optional() .describe("Region code for localized results (e.g., 'us', 'uk', 'ca', 'au')"), safeSearch: z .enum(["off", "moderate", "strict"]) .optional() .describe("Safe search filter level"), timeRange: z .enum(["hour", "day", "week", "month", "year"]) .optional() .describe("Time range filter for recent results"), }), annotations: { title: "Enhanced Web Search", readOnlyHint: true, openWorldHint: true, }, execute: async (args, { log }) => { try { log.info("Starting enhanced web search", { query: args.query, limit: args.limit, options: { language: args.language, region: args.region, safeSearch: args.safeSearch, timeRange: args.timeRange, }, }); const searchOptions: SearchOptions = { limit: args.limit, language: args.language, region: args.region, safeSearch: args.safeSearch, timeRange: args.timeRange, }; const results = await performSearch(args.query, searchOptions); log.info("Search completed successfully", { resultCount: results.length, query: args.query, }); if (results.length === 0) { return "No search results found. This could be due to:\n" + "- Very specific or uncommon search terms\n" + "- Temporary blocking by Google (try again later)\n" + "- Network connectivity issues\n" + "- Search filters being too restrictive"; } // Format results in a readable way const formattedResults = results.map((result, index) => { return `${index + 1}. **${result.title}**\n` + ` URL: ${result.url}\n` + ` Description: ${result.description || "No description available"}\n`; }).join("\n"); return `Found ${results.length} search results for "${args.query}":\n\n${formattedResults}`; } catch (error) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; log.error("Search failed", { query: args.query, error: errorMessage, }); // Provide helpful error messages to users if (errorMessage.includes("Rate limited")) { return `Search temporarily unavailable due to rate limiting. Please try again in a few minutes.\n\nQuery: "${args.query}"`; } else if (errorMessage.includes("Access denied") || errorMessage.includes("blocked")) { return `Search request was blocked by Google. This can happen with frequent requests. Please try again later.\n\nQuery: "${args.query}"`; } else if (errorMessage.includes("timeout")) { return `Search request timed out. Please check your internet connection and try again.\n\nQuery: "${args.query}"`; } else { return `Search failed: ${errorMessage}\n\nQuery: "${args.query}"\n\nTip: Try rephrasing your search query or try again later.`; } } }, });
• src/search.ts:10-22 (schema)

  TypeScript interfaces defining SearchResult output structure and SearchOptions input for the performSearch function.
  export interface SearchResult { description: string; title: string; url: string; } export interface SearchOptions { limit?: number; language?: string; region?: string; safeSearch?: "moderate" | "off" | "strict"; timeRange?: "day" | "hour" | "month" | "week" | "year"; }