G-Search MCP

To use G-Search MCP as a tool within Claude Desktop, add the following configuration to your claude_desktop_config.json file.

File Locations:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "g-search": {
      "command": "npx",
      "args": ["-y", "g-search-mcp"]
    }
  }
}

If you prefer to build the server from source, ensure you have Node.js 18+ and NPM/Yarn installed.

1. Clone and enter the repository:

   git clone https://github.com/jae-jae/g-search-mcp.git
   cd g-search-mcp

2. Install dependencies:

   npm install

3. Install Playwright browser:

   npm run install-browser

4. Build the server:

   npm run build

npm install && npm run install-browser && npm run build

You can run G-Search MCP directly using npx.

First-time setup: You must install the required Playwright browser before running the server:

npx playwright install chromium

Run the server:

npx -y g-search-mcp

Run in Debug Mode (shows the browser window):

npx -y g-search-mcp --debug

You can dynamically adjust the search tool's parameters by providing specific instructions in your prompt:

• Increase Result Quantity: Use phrases like Please return the top 20 search results for each keyword to set the limit parameter.
• Increase Timeout: Use phrases like Please set the page loading timeout to 120 seconds to adjust the timeout parameter (e.g., to 120000).
• Change Locale/Region: Use phrases like Please use Chinese locale (zh-CN) for searching to set the locale parameter.
• Enable Debug Mode: Use Please enable debug mode for this search operation to set debug: true for a specific call, which will show the browser window.

The googleSearch service uses a debug option to control browser lifecycle and visibility. When debug is set to true:

• The browser runs in headful mode (not headless).
• The browser instance is not closed automatically after searches complete, allowing for manual inspection of the browser state.

When debug is false (default):

• The browser runs in headless mode.
• The browser instance is automatically closed after all searches in a batch are completed.

// Example of how debug mode affects the service
// If options.debug is true, the browser stays open
const searchOptions = { debug: true };

The server is designed to run as an MCP (Model Context Protocol) server using StdioServerTransport. It initializes a Google Search server instance and connects it to the standard input/output streams, allowing AI agents or MCP clients to interact with Google Search via the provided tools.

// The server is initialized and started via the main entrypoint
// It uses StdioServerTransport for communication
import { createServer } from "./server.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = createServer();
const transport = new StdioServerTransport();
await server.connect(transport);

When performing multiple searches (e.g., using a multi-search pattern), the service manages state files to prevent data corruption or conflicts between concurrent queries.

If a stateFile is provided in the options, the service appends an index to it for each query (e.g., path/to/state-0.json, path/to/state-1.json). If no stateFile is provided, it defaults to a pattern of ./browser-state-${index}.json.

// If options.stateFile is 'my-session',
// search #0 uses 'my-session-0.json'
// search #1 uses 'my-session-1.json'

The search tool allows you to perform Google searches for multiple keywords simultaneously. You provide an array of queries, and the tool returns search results for each.

Input Parameters:

• queries (required): An array of strings representing the search queries to perform.
• limit (number): Maximum number of results to return per query. Defaults to 10.
• timeout (number): Page loading timeout in milliseconds. Defaults to 60000.
• noSaveState (boolean): If true, avoids saving browser state. Defaults to false.
• locale (string): Locale setting for search results (e.g., en-US). Defaults to en-US.
• debug (boolean): Enables debug mode (showing the browser window). This parameter overrides the --debug command line flag if provided.

{
  "queries": ["keyword1", "keyword2"],
  "limit": 5,
  "locale": "en-GB",
  "debug": true
}

The multiGoogleSearch function allows you to execute an array of search queries. It is intended for batch processing multiple search terms efficiently.

import { multiGoogleSearch } from './services/googleSearch.js';

const queries = ['typescript tutorial', 'playwright automation', 'mcp protocol'];
const allResults = await multiGoogleSearch(queries, { limit: 5 });

// allResults is an array of SearchResponse objects

The googleSearch function executes a Google search using a Playwright-driven browser. It is designed to bypass bot detection by using randomized device fingerprints, realistic browser configurations, and managing browser state (cookies/storage) to avoid repeated CAPTCHAs.

By default, it runs in headless mode unless the debug option is set to true. If a CAPTCHA is detected while in headless mode, the service will automatically attempt to restart the browser in non-headless mode to allow for manual verification or automated handling.

import { googleSearch } from './services/googleSearch.js';

const results = await googleSearch('your search query', {
  limit: 5,
  timeout: 30000,
  locale: 'en-US',
  stateFile: './my-browser-state.json',
  debug: false
});

console.log(results.results);

The src/tools/index.ts file serves as the central registry for MCP tools. It exports two main objects used to integrate the tools into an MCP server:

1. tools: An array containing the tool definitions (metadata like name, description, and input schema).
2. toolHandlers: An object mapping tool names to their corresponding implementation functions.

To add a new tool to the MCP server, you must add its definition to the tools array and its implementation to the toolHandlers object using the tool's name as the key.

import { tools, toolHandlers } from './tools/index.js';

// Example of how these are used to initialize an MCP server
// server.setTools(tools);
// server.setHandlers(toolHandlers);