### Initialize MCP Server with Stdio Transport Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Sets up and starts the MCP server utilizing the standard input/output (stdio) transport mechanism. This is the primary method for launching the server. It requires the SDK to be installed. ```typescript import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { createServer } from "./server.js"; async function main() { const server = createServer(); const transport = new StdioServerTransport(); await server.connect(transport); console.error("Server started"); } main().catch((error) => { console.error(`Server error: ${error}`); process.exit(1); }); ``` -------------------------------- ### Run G-Search MCP via npx Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This command allows you to run the G-Search MCP server directly using Node Package Execute (npx). It's a quick way to start the server without a global installation. Ensure Node.js and npm are installed. ```bash npx -y g-search-mcp ``` -------------------------------- ### MCP Tool Call and Response Examples (JSON) Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Illustrates a typical MCP tool call request to the 'search' tool with multiple queries and parameters, followed by an example of the structured JSON response containing search results. This shows the communication format between an AI assistant and the G-Search MCP server. ```json { "method": "tools/call", "params": { "name": "search", "arguments": { "queries": ["machine learning", "artificial intelligence"], "limit": 10, "timeout": 60000, "locale": "en-US", "debug": false } } } ``` ```json { "content": [ { "type": "text", "text": "{\"searches\":[{\"query\":\"machine learning\",\"results\":[{\"title\":\"What is Machine Learning? | IBM\",\"link\":\"https://www.ibm.com/topics/machine-learning\",\"snippet\":\"Machine learning is a branch of artificial intelligence (AI) and computer science which focuses on the use of data and algorithms to imitate the way that humans learn, gradually improving its accuracy.\"},{\"title\":\"Machine Learning - Wikipedia\",\"link\":\"https://en.wikipedia.org/wiki/Machine_learning\",\"snippet\":\"Machine learning is a field of study in artificial intelligence concerned with the development and study of statistical algorithms that can learn from data...\"}]},{\"query\":\"artificial intelligence\",\"results\":[{\"title\":\"What is Artificial Intelligence (AI)? | IBM\",\"link\":\"https://www.ibm.com/topics/artificial-intelligence\",\"snippet\":\"Artificial intelligence leverages computers and machines to mimic the problem-solving and decision-making capabilities of the human mind.\"},{\"title\":\"Artificial Intelligence - Wikipedia\",\"link\":\"https://en.wikipedia.org/wiki/Artificial_intelligence\",\"snippet\":\"Artificial intelligence is the intelligence of machines or software, as opposed to the intelligence of humans or animals...\"}]}]}" } ] } ``` -------------------------------- ### Install Node.js Dependencies Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This command installs all the necessary Node.js packages and dependencies required for the G-Search MCP project. It should be run after cloning the repository. Requires Node.js and npm (or Yarn) to be installed. ```bash npm install ``` -------------------------------- ### Install Playwright Browsers from Source Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This command installs the Playwright browser binaries when building G-Search MCP from source. It's an alternative to the global `npx playwright install chromium` and is specific to the project's installation script. Requires Node.js and npm. ```bash npm run install-browser ``` -------------------------------- ### Enable Debug Mode Dynamically Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This example illustrates how to enable debug mode for a specific search operation, even if the server was not initially started with the `--debug` flag. It translates a natural language request into setting the `debug: true` parameter for the `search` tool. ```text Please enable debug mode for this search operation ``` -------------------------------- ### Install Playwright Browser Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This command installs the necessary browser binaries for Playwright, which G-Search MCP uses to perform automated browser interactions for searching. This is a prerequisite for running the search functionality. ```bash npx playwright install chromium ``` -------------------------------- ### Claude Desktop MCP Server Configuration (JSON) Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Provides JSON configurations for integrating the G-Search MCP server into Claude Desktop on macOS and Windows. Includes examples for basic setup, enabling debug mode, and enabling logging, specifying the command and arguments to launch the server. ```json // MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json // Windows: %APPDATA%/Claude/claude_desktop_config.json { "mcpServers": { "g-search": { "command": "npx", "args": ["-y", "g-search-mcp"] } } } ``` ```json // With debug mode enabled { "mcpServers": { "g-search": { "command": "npx", "args": ["-y", "g-search-mcp", "--debug"] } } } ``` ```json // With logging enabled { "mcpServers": { "g-search": { "command": "npx", "args": ["-y", "g-search-mcp", "--log"] } } } ``` -------------------------------- ### Running the G-Search-MCP Application Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Provides various command-line methods to run the g-search-mcp application using npx. It includes options for direct execution, enabling debug mode for a visible browser, activating logging, and installing necessary Playwright browsers. ```bash # Run directly with npx npx -y g-search-mcp # Run with debug mode (visible browser) npx -y g-search-mcp --debug # Run with logging enabled npx -y g-search-mcp --log # Install Playwright browser (required on first run) npx playwright install chromium ``` -------------------------------- ### Clone G-Search MCP Repository Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This command clones the G-Search MCP project repository from GitHub to your local machine. This is the first step in installing and building the project from source. Requires Git to be installed. ```bash git clone https://github.com/jae-jae/g-search-mcp.git cd g-search-mcp ``` -------------------------------- ### G-Search MCP Search Functionality Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This example illustrates how to use the `search` tool provided by G-Search MCP. It takes an array of `queries` and returns structured JSON results, including titles, links, and snippets. It supports parameters like `limit`, `timeout`, `noSaveState`, `locale`, and `debug`. ```json { "searches": [ { "query": "machine learning", "results": [ { "title": "What is Machine Learning? | IBM", "link": "https://www.ibm.com/topics/machine-learning", "snippet": "Machine learning is a branch of artificial intelligence (AI) and computer science which focuses on the use of data and algorithms to imitate the way that humans learn, gradually improving its accuracy." }, ... ] }, { "query": "artificial intelligence", "results": [ { "title": "What is Artificial Intelligence (AI)? | IBM", "link": "https://www.ibm.com/topics/artificial-intelligence", "snippet": "Artificial intelligence leverages computers and machines to mimic the problem-solving and decision-making capabilities of the human mind." }, ... ] } ] } ``` -------------------------------- ### Build G-Search MCP from Source Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This command compiles the G-Search MCP project after installing dependencies and Playwright browsers. It generates the necessary build artifacts to run the server. Requires Node.js and npm. ```bash npm run build ``` -------------------------------- ### Increase Page Loading Timeout Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This example demonstrates how to increase the `timeout` parameter for search operations. It converts a specified duration in seconds into milliseconds, which is the unit expected by the `timeout` parameter in G-Search MCP. ```text Please set the page loading timeout to 120 seconds ``` -------------------------------- ### Set Search Result Limit Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This example shows how to adjust the `limit` parameter for a search query, requesting a specific number of results. It translates a natural language request into the corresponding `limit` parameter for the G-Search MCP `search` tool. ```text Please return the top 20 search results for each keyword ``` -------------------------------- ### Set Search Locale Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This example shows how to specify a different locale for search results using the `locale` parameter. It translates a request for a specific language/region into the correct locale string for the G-Search MCP `search` tool. ```text Please use Chinese locale (zh-CN) for searching ``` -------------------------------- ### MCP Search Tool Definition (TypeScript) Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Defines the 'search' tool for the MCP server, specifying input parameters like queries, result limits, timeouts, and debug options. This schema guides how AI assistants should structure their search requests. ```typescript { name: "search", description: "Search on Google for multiple keywords and return the results", inputSchema: { type: "object", properties: { queries: { type: "array", items: { type: "string" }, description: "Array of search queries to perform" }, limit: { type: "number", description: "Maximum number of results to return per query (default: 10)" }, timeout: { type: "number", description: "Page loading timeout in milliseconds (default: 60000)" }, noSaveState: { type: "boolean", description: "Whether to avoid saving browser state (default: false)" }, locale: { type: "string", description: "Locale setting for search results (default: en-US)" }, debug: { type: "boolean", description: "Enable debug mode showing browser window" } }, required: ["queries"] } } ``` -------------------------------- ### TypeScript: Rate Limiting with Delays Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Demonstrates implementing rate limiting by introducing a delay between consecutive searches. A loop iterates through queries, performs a search, logs the results, and then waits for 5 seconds before the next iteration. ```typescript const queries = ["query1", "query2", "query3"]; for (const query of queries) { const result = await googleSearch(query, { limit: 10 }); console.log(`Got ${result.results.length} results for: ${query}`); await new Promise(resolve => setTimeout(resolve, 5000)); // 5s delay } ``` -------------------------------- ### Configure G-Search MCP Server Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md This JSON configuration snippet demonstrates how to register the G-Search MCP server within the Claude Desktop application's configuration file. It specifies the command to execute and its arguments, allowing Claude to interact with the G-Search MCP server. ```json { "mcpServers": { "g-search": { "command": "npx", "args": ["-y", "g-search-mcp"] } } } ``` -------------------------------- ### Run G-Search MCP in Debug Mode Source: https://github.com/jae-jae/g-search-mcp/blob/main/README.md Executing the G-Search MCP server with the `--debug` flag enables a visual mode where the browser window used for searching is displayed. This is useful for troubleshooting or observing the search process. Requires Node.js and npm. ```bash npx -y g-search-mcp --debug ``` -------------------------------- ### TypeScript: Development/Testing with Visible Browser Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Shows how to enable visible browser mode for development and testing purposes. The `debug: true` option makes the browser visible, and `noSaveState: true` prevents persistence of browser state during these sessions. ```typescript const devResult = await googleSearch("test query", { limit: 5, debug: true, // Show browser noSaveState: true, // Don't persist state timeout: 120000 }); ``` -------------------------------- ### Implement Google Search MCP Tool Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Handles MCP tool calls for executing Google searches. The `searchGoogle` function processes arguments received from an MCP client, including search queries and configuration options. It returns results formatted as JSON within a 'text' content type. Includes error handling for invalid arguments and dynamic debug mode overrides. ```typescript import { searchGoogle } from "./tools/searchGoogle.js"; // Tool handler processes arguments from MCP client const args = { queries: ["machine learning", "deep learning"], limit: 15, timeout: 90000, locale: "en-US", debug: false, noSaveState: false }; try { const response = await searchGoogle(args); console.log(response); } catch (error) { console.error(`Search failed: ${error.message}`); } // Error handling for invalid arguments try { await searchGoogle({ queries: [] }); // Empty array } catch (error) { console.error(error.message); // "At least one search query is required" } // Dynamic debug mode override const debugSearch = await searchGoogle({ queries: ["test query"], debug: true // Overrides command-line --debug flag }); ``` -------------------------------- ### Handle Google CAPTCHA Challenges Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Automatically detects and handles Google CAPTCHA challenges by checking for specific URL patterns or text. In headless mode, it restarts the browser in visible mode for manual completion. In debug mode, it keeps the browser visible. ```bash # CAPTCHA is automatically detected by checking for: # - google.com/sorry/index # - google.com/sorry # - recaptcha # - captcha # - "unusual traffic" text # Behavior in headless mode: # 1. CAPTCHA detected → automatically restart in visible browser mode # 2. User completes CAPTCHA manually # 3. Search continues automatically # Behavior in debug mode (visible browser): # 1. CAPTCHA detected → browser remains visible # 2. User completes CAPTCHA manually # 3. Wait for navigation back to search results # 4. Continue with search extraction ``` -------------------------------- ### TypeScript: Batch Research with High Result Count Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Demonstrates performing batch research with a high number of results per query. It utilizes `multiGoogleSearch` for parallel execution and configures higher limits and longer timeouts for potentially slow pages. State saving is enabled to mitigate CAPTCHA challenges. ```typescript const researchQueries = [ "climate change effects 2024", "renewable energy technologies", "carbon capture methods" ]; const research = await multiGoogleSearch(researchQueries, { limit: 25, // More results per query timeout: 180000, // 3-minute timeout for slow pages locale: "en-US", noSaveState: false // Save state to avoid CAPTCHA }); ``` -------------------------------- ### MCP Search Tool Source: https://context7.com/jae-jae/g-search-mcp/llms.txt This tool allows for parallel Google searches with multiple keywords. It accepts an array of queries and optional parameters for limiting results, setting timeouts, managing browser state, specifying locale, and enabling debug mode. ```APIDOC ## POST /tools/call (MCP Tool Call) ### Description Initiates a search operation using the 'search' tool exposed by the G-Search MCP server. This endpoint allows for parallel Google searches with specified keywords and configuration options. ### Method POST ### Endpoint /tools/call ### Parameters #### Request Body - **method** (string) - Required - The MCP method to call, must be 'tools/call'. - **params** (object) - Required - Parameters for the tool call. - **name** (string) - Required - The name of the tool to call, must be 'search'. - **arguments** (object) - Required - Arguments for the 'search' tool. - **queries** (array of strings) - Required - An array of search queries to perform. - **limit** (number) - Optional - Maximum number of results to return per query (default: 10). - **timeout** (number) - Optional - Page loading timeout in milliseconds (default: 60000). - **noSaveState** (boolean) - Optional - Whether to avoid saving browser state (default: false). - **locale** (string) - Optional - Locale setting for search results (default: en-US). - **debug** (boolean) - Optional - Enable debug mode, showing the browser window (default: false). ### Request Example ```json { "method": "tools/call", "params": { "name": "search", "arguments": { "queries": ["machine learning", "artificial intelligence"], "limit": 10, "timeout": 60000, "locale": "en-US", "debug": false } } } ``` ### Response #### Success Response (200) - **content** (array) - Contains the search results. - **type** (string) - The type of content, expected to be 'text'. - **text** (string) - A JSON string containing the search results, structured by query. #### Response Example ```json { "content": [ { "type": "text", "text": "{\"searches\":[{\"query\":\"machine learning\",\"results\":[{\"title\":\"What is Machine Learning? | IBM\",\"link\":\"https://www.ibm.com/topics/machine-learning\",\"snippet\":\"Machine learning is a branch of artificial intelligence (AI) and computer science which focuses on the use of data and algorithms to imitate the way that humans learn, gradually improving its accuracy.\"},{\"title\":\"Machine Learning - Wikipedia\",\"link\":\"https://en.wikipedia.org/wiki/Machine_learning\",\"snippet\":\"Machine learning is a field of study in artificial intelligence concerned with the development and study of statistical algorithms that can learn from data...\"}]},{\"query\":\"artificial intelligence\",\"results\":[{\"title\":\"What is Artificial Intelligence (AI)? | IBM\",\"link\":\"https://www.ibm.com/topics/artificial-intelligence\",\"snippet\":\"Artificial intelligence leverages computers and machines to mimic the problem-solving and decision-making capabilities of the human mind.\"},{\"title\":\"Artificial Intelligence - Wikipedia\",\"link\":\"https://en.wikipedia.org/wiki/Artificial_intelligence\",\"snippet\":\"Artificial intelligence is the intelligence of machines or software, as opposed to the intelligence of humans or animals...\"}]}]}" } ] } ``` ``` -------------------------------- ### Manage Browser Fingerprints and State Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Automatically saves and loads browser state (cookies, origins) and fingerprints (device type, locale, timezone, etc.) to avoid detection and CAPTCHAs. State can be saved to a custom file or disabled entirely. The fingerprint includes device details, locale, timezone, color scheme, and user agent settings. ```typescript // Browser state is automatically saved to avoid CAPTCHA // Default location: ./browser-state.json // Fingerprint saved to: ./browser-state-fingerprint.json // Fingerprint includes: // - Device type (Desktop Chrome/Firefox/Safari/Edge) // - Locale (based on system or user setting) // - Timezone (auto-detected from system) // - Color scheme (dark/light based on time) // - User agent and viewport settings // Custom state file location const result = await googleSearch("query", { stateFile: "./custom/path/state.json" }); // Disable state saving (fresh fingerprint each time) const result = await googleSearch("query", { noSaveState: true }); // State file structure (example) // { // "cookies": [...], // "origins": [...] // } // Fingerprint file structure (example) // { // "fingerprint": { // "deviceName": "Desktop Chrome", // "locale": "en-US", // "timezoneId": "America/New_York", // "colorScheme": "light", // "reducedMotion": "no-preference", // "forcedColors": "none" // }, // "googleDomain": "https://www.google.com" // } ``` -------------------------------- ### Execute Multi-Query Parallel Google Search Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Performs multiple Google searches concurrently using a single browser instance with multiple tabs. The `multiGoogleSearch` function takes an array of queries and options, returning results for each query in parallel. It is designed for efficiency when executing numerous searches. ```typescript import { multiGoogleSearch } from "./services/googleSearch.js"; // Parallel search with multiple queries const queries = [ "machine learning", "artificial intelligence", "deep learning", "neural networks" ]; const results = await multiGoogleSearch(queries, { limit: 10, timeout: 60000, locale: "en-US", debug: false }); console.log(results); // Process results results.forEach((searchResponse) => { console.log(`\nQuery: ${searchResponse.query}`); searchResponse.results.forEach((result, index) => { console.log(`${index + 1}. ${result.title}`); console.log(` ${result.link}`); console.log(` ${result.snippet}`); }); }); ``` -------------------------------- ### TypeScript: Error Recovery with Retries Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Implements an error recovery mechanism with automatic retries for search queries. The `searchWithRetry` function attempts a search multiple times, logs errors, and waits before retrying. It throws an error if all retries fail. ```typescript async function searchWithRetry(query: string, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { const result = await googleSearch(query, { timeout: 60000 }); if (result.results.length > 0 && result.results[0].title !== "Search failed") { return result; } } catch (error) { console.error(`Attempt ${i + 1} failed: ${error.message}`); if (i === maxRetries - 1) throw error; await new Promise(resolve => setTimeout(resolve, 10000)); } } } ``` -------------------------------- ### Configure Logging System Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Implements a configurable logging system using a `logger` utility. Logs are disabled by default and can be enabled via the `--log` command-line flag. Log messages (info, warn, error, debug) are written to stderr with timestamps. ```typescript import { logger } from "./utils/logger.js"; // Logger is disabled by default // Enable with --log command line flag logger.info("Starting search operation"); logger.warn("CAPTCHA detected"); logger.error("Search failed"); logger.debug("Debug information"); // Logs are written to stderr with timestamps // Example output: // 2025-12-16T01:42:15.123Z [INFO] Starting search operation // 2025-12-16T01:42:16.456Z [WARN] CAPTCHA detected // 2025-12-16T01:42:17.789Z [ERROR] Search failed // Enable logging when running // npx -y g-search-mcp --log ``` -------------------------------- ### Perform Single Google Search with Anti-Detection Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Executes a single Google search query using the `googleSearch` function. This function includes built-in anti-detection features and allows for customizable options like the number of results, timeout, locale, and debug mode. It can optionally use an existing browser instance. ```typescript import { googleSearch } from "./services/googleSearch.js"; import { chromium } from "playwright"; // Basic search const result = await googleSearch("machine learning", { limit: 10, timeout: 60000, locale: "en-US", debug: false }); console.log(result); // Search with custom options const customResult = await googleSearch("TypeScript tutorials", { limit: 20, timeout: 120000, locale: "zh-CN", noSaveState: true, debug: true, stateFile: "./custom-state.json" }); // Search with existing browser instance const browser = await chromium.launch({ headless: true }); const result1 = await googleSearch("query 1", { limit: 5 }, browser); const result2 = await googleSearch("query 2", { limit: 5 }, browser); await browser.close(); ``` -------------------------------- ### Automate CAPTCHA Recovery Flow Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Demonstrates the CAPTCHA recovery process in headless and debug modes. If a CAPTCHA is detected in headless mode, the browser restarts visibly for manual resolution. In debug mode, the browser remains visible throughout the process. ```typescript // Example of CAPTCHA recovery flow const result = await googleSearch("query", { debug: false // Headless mode }); // If CAPTCHA detected: // [GoogleSearch] CAPTCHA detected, will restart browser in non-headless mode... // [Browser window opens] // [User completes CAPTCHA] // [Search continues automatically] // [Results returned] // In debug mode, browser stays visible throughout const debugResult = await googleSearch("query", { debug: true // User can manually handle CAPTCHA }); ``` -------------------------------- ### TypeScript: International Search Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Illustrates performing an international search using a specific locale. The `googleSearch` function is used with a query in Japanese and the Chinese locale (`zh-CN`) is specified for the search results. ```typescript const intlResult = await googleSearch("东京旅游攻略", { limit: 15, locale: "zh-CN", // Chinese locale timeout: 90000 }); ``` -------------------------------- ### Define TypeScript Types for Search Source: https://context7.com/jae-jae/g-search-mcp/llms.txt Provides core TypeScript interfaces for search operations, including options for controlling search behavior (limit, timeout, state saving, locale, debug mode) and structures for representing search results and responses. ```typescript // Search options interface SearchOptions { limit?: number; // Max results per query (default: 10) timeout?: number; // Page timeout in ms (default: 60000) stateFile?: string; // Browser state file path noSaveState?: boolean; // Skip saving state (default: false) locale?: string; // Locale setting (default: "en-US") debug?: boolean; // Show browser window (default: false) } // Single search result interface SearchResult { title: string; // Page title link: string; // URL snippet: string; // Description/snippet } // Response for single query interface SearchResponse { query: string; results: SearchResult[]; } // Response for multiple queries interface MultiSearchResponse { searches: SearchResponse[]; } // Usage example const options: SearchOptions = { limit: 20, timeout: 120000, locale: "zh-CN", debug: true }; const response: SearchResponse = await googleSearch("query", options); const multiResponse: MultiSearchResponse = { searches: [response] }; ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.