Google Search Tool logo

Google Search Tool

Organization
web-agent-master

A Playwright-based Node.js tool that bypasses search engine anti-scraping mechanisms to execute Google searches. Local alternative to SERP APIs with MCP server integration.

Publisherweb-agent-master
Repositorygoogle-search
LanguageTypeScript
Forks
102
Stars
620
Available tools
0
Transport typestdio
Categories
Links
  • Connect tools to AI workflows

    Google Search Tool exposes MCP capabilities that can be used by compatible AI clients and agents.

  • 0 available tools

    Browse the callable actions below, including names and descriptions when provided by the server.

  • Ready-to-copy setup

    Use the installation snippets to configure this server in your preferred MCP client.

  • Open source signals

    620 stars and 102 forks from the linked repository.

Google Search Tool

A Playwright-based Node.js tool that bypasses search engine anti-scraping mechanisms to execute Google searches and extract results. It can be used directly as a command-line tool or as a Model Context Protocol (MCP) server to provide real-time search capabilities to AI assistants like Claude.

Star History Chart

中文文档

Key Features

  • Local SERP API Alternative: No need to rely on paid search engine results API services, all searches are executed locally
  • Advanced Anti-Bot Detection Bypass Techniques:
    • Intelligent browser fingerprint management that simulates real user behavior
    • Automatic saving and restoration of browser state to reduce verification frequency
    • Smart headless/headed mode switching, automatically switching to headed mode when verification is needed
    • Randomization of device and locale settings to reduce detection risk
  • Raw HTML Retrieval: Ability to fetch the raw HTML of search result pages (with CSS and JavaScript removed) for analysis and debugging when Google's page structure changes
  • Page Screenshot: Automatically captures and saves a full-page screenshot when saving HTML content
  • MCP Server Integration: Provides real-time search capabilities to AI assistants like Claude without requiring additional API keys
  • Completely Open Source and Free: All code is open source with no usage restrictions, freely customizable and extensible

Technical Features

  • Developed with TypeScript, providing type safety and better development experience
  • Browser automation based on Playwright, supporting multiple browser engines
  • Command-line parameter support for search keywords
  • MCP server support for AI assistant integration
  • Returns search results with title, link, and snippet
  • Option to retrieve raw HTML of search result pages for analysis
  • JSON format output
  • Support for both headless and headed modes (for debugging)
  • Detailed logging output
  • Robust error handling
  • Browser state saving and restoration to effectively avoid anti-bot detection

Installation

bash
# Install from source
git clone https://github.com/web-agent-master/google-search.git
cd google-search
# Install dependencies
npm install
# Or using yarn
yarn
# Or using pnpm
pnpm install

# Compile TypeScript code
npm run build
# Or using yarn
yarn build
# Or using pnpm
pnpm build

# Link package globally (required for MCP functionality)
npm link
# Or using yarn
yarn link
# Or using pnpm
pnpm link

Windows Environment Notes

This tool has been specially adapted for Windows environments:

  1. .cmd files are provided to ensure command-line tools work properly in Windows Command Prompt and PowerShell
  2. Log files are stored in the system temporary directory instead of the Unix/Linux /tmp directory
  3. Windows-specific process signal handling has been added to ensure proper server shutdown
  4. Cross-platform file path handling is used to support Windows path separators

Usage

Command Line Tool

bash
# Direct command line usage
google-search "search keywords"

# Using command line options
google-search --limit 5 --timeout 60000 --no-headless "search keywords"

# Or using npx
npx google-search-cli "search keywords"

# Run in development mode
pnpm dev "search keywords"

# Run in debug mode (showing browser interface)
pnpm debug "search keywords"

# Get raw HTML of search result page
google-search "search keywords" --get-html

# Get HTML and save to file
google-search "search keywords" --get-html --save-html

# Get HTML and save to specific file
google-search "search keywords" --get-html --save-html --html-output "./output.html"

Command Line Options

  • -l, --limit <number>: Result count limit (default: 10)
  • -t, --timeout <number>: Timeout in milliseconds (default: 60000)
  • --no-headless: Show browser interface (for debugging)
  • --remote-debugging-port <number>: Enable remote debugging port (default: 9222)
  • --state-file <path>: Browser state file path (default: ./browser-state.json)
  • --no-save-state: Don't save browser state
  • --get-html: Retrieve raw HTML of search result page instead of parsing results
  • --save-html: Save HTML to file (used with --get-html)
  • --html-output <path>: Specify HTML output file path (used with --get-html and --save-html)
  • -V, --version: Display version number
  • -h, --help: Display help information

Output Example

json
{
  "query": "deepseek",
  "results": [
    {
      "title": "DeepSeek",
      "link": "https://www.deepseek.com/",
      "snippet": "DeepSeek-R1 is now live and open source, rivaling OpenAI's Model o1. Available on web, app, and API. Click for details. Into ..."
    },
    {
      "title": "DeepSeek",
      "link": "https://www.deepseek.com/",
      "snippet": "DeepSeek-R1 is now live and open source, rivaling OpenAI's Model o1. Available on web, app, and API. Click for details. Into ..."
    },
    {
      "title": "deepseek-ai/DeepSeek-V3",
      "link": "https://github.com/deepseek-ai/DeepSeek-V3",
      "snippet": "We present DeepSeek-V3, a strong Mixture-of-Experts (MoE) language model with 671B total parameters with 37B activated for each token."
    }
    // More results...
  ]
}

HTML Output Example

When using the --get-html option, the output will include information about the HTML content:

json
{
  "query": "playwright automation",
  "url": "https://www.google.com/",
  "originalHtmlLength": 1291733,
  "cleanedHtmlLength": 456789,
  "htmlPreview": "<!DOCTYPE html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"zh-CN\"><head><meta charset=\"UTF-8\"><meta content=\"dark light\" name=\"color-scheme\"><meta content=\"origin\" name=\"referrer\">..."
}

If you also use the --save-html option, the output will include the path where the HTML was saved:

json
{
  "query": "playwright automation",
  "url": "https://www.google.com/",
  "originalHtmlLength": 1292241,
  "cleanedHtmlLength": 458976,
  "savedPath": "./google-search-html/playwright_automation-2025-04-06T03-30-06-852Z.html",
  "screenshotPath": "./google-search-html/playwright_automation-2025-04-06T03-30-06-852Z.png",
  "htmlPreview": "<!DOCTYPE html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"zh-CN\">..."
}

MCP Server

This project provides Model Context Protocol (MCP) server functionality, allowing AI assistants like Claude to directly use Google search capabilities. MCP is an open protocol that enables AI assistants to safely access external tools and data.

bash
# Build the project
pnpm build

Integration with Claude Desktop

  1. Edit the Claude Desktop configuration file:

    • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
      • Usually located at C:\Users\username\AppData\Roaming\Claude\claude_desktop_config.json
      • You can access it directly by entering %APPDATA%\Claude in Windows Explorer address bar
  2. Add server configuration and restart Claude

json
{
  "mcpServers": {
    "google-search": {
      "command": "npx",
      "args": ["google-search-mcp"]
    }
  }
}

For Windows environments, you can also use the following configurations:

  1. Using cmd.exe with npx:
json
{
  "mcpServers": {
    "google-search": {
      "command": "cmd.exe",
      "args": ["/c", "npx", "google-search-mcp"]
    }
  }
}
  1. Using node with full path (recommended if you encounter issues with the above method):
json
{
  "mcpServers": {
    "google-search": {
      "command": "node",
      "args": ["C:/path/to/your/google-search/dist/src/mcp-server.js"]
    }
  }
}

Note: For the second method, you must replace C:/path/to/your/google-search with the actual full path to where you installed the google-search package.

After integration, you can directly use search functionality in Claude, such as "search for the latest AI research".

Project Structure

google-search/
├── package.json          # Project configuration and dependencies
├── tsconfig.json         # TypeScript configuration
├── src/
│   ├── index.ts          # Entry file (command line parsing and main logic)
│   ├── search.ts         # Search functionality implementation (Playwright browser automation)
│   ├── mcp-server.ts     # MCP server implementation
│   └── types.ts          # Type definitions (interfaces and type declarations)
├── dist/                 # Compiled JavaScript files
├── bin/                  # Executable files
│   └── google-search     # Command line entry script
├── README.md             # Project documentation
└── .gitignore            # Git ignore file

Technology Stack

  • TypeScript: Development language, providing type safety and better development experience
  • Node.js: Runtime environment for executing JavaScript/TypeScript code
  • Playwright: For browser automation, supporting multiple browsers
  • Commander: For parsing command line arguments and generating help information
  • Model Context Protocol (MCP): Open protocol for AI assistant integration
  • MCP SDK: Development toolkit for implementing MCP servers
  • Zod: Schema definition library for validation and type safety
  • pnpm: Efficient package management tool, saving disk space and installation time

Development Guide

All commands can be run in the project root directory:

bash
# Install dependencies
pnpm install

# Install Playwright browsers
pnpm run postinstall

# Compile TypeScript code
pnpm build

# Clean compiled output
pnpm clean

CLI Development

bash
# Run in development mode
pnpm dev "search keywords"

# Run in debug mode (showing browser interface)
pnpm debug "search keywords"

# Run compiled code
pnpm start "search keywords"

# Test search functionality
pnpm test

MCP Server Development

bash
# Run MCP server in development mode
pnpm mcp

# Run compiled MCP server
pnpm mcp:build

Error Handling

The tool has built-in robust error handling mechanisms:

  • Friendly error messages when browser startup fails
  • Automatic error status return for network connection issues
  • Detailed logs for search result parsing failures
  • Graceful exit and useful information return in timeout situations

Notes

General Notes

  • This tool is for learning and research purposes only
  • Please comply with Google's terms of service and policies
  • Do not send requests too frequently to avoid being blocked by Google
  • Some regions may require a proxy to access Google
  • Playwright needs to install browsers, which will be automatically downloaded on first use

State Files

  • State files contain browser cookies and storage data, please keep them secure
  • Using state files can effectively avoid Google's anti-bot detection and improve search success rate

MCP Server

  • MCP server requires Node.js v16 or higher
  • When using the MCP server, please ensure Claude Desktop is updated to the latest version
  • When configuring Claude Desktop, use absolute paths to the MCP server file

Windows-Specific Notes

  • In Windows environments, you may need administrator privileges to install Playwright browsers for the first time
  • If you encounter permission issues, try running Command Prompt or PowerShell as administrator
  • Windows Firewall may block Playwright browser network connections; allow access when prompted
  • Browser state files are saved by default in the user's home directory as .google-search-browser-state.json
  • Log files are stored in the system temporary directory under the google-search-logs folder

Comparison with Commercial SERP APIs

Compared to paid search engine results API services (such as SerpAPI), this project offers the following advantages:

  • Completely Free: No API call fees
  • Local Execution: All searches are executed locally, no dependency on third-party services
  • Privacy Protection: Search queries are not recorded by third parties
  • Customizability: Fully open source, can be modified and extended as needed
  • No Usage Limits: Not subject to API call count or frequency limitations
  • MCP Integration: Native support for integration with AI assistants like Claude

Installation

TypingMind
{
  "mcpServers": {
    "web-agent-master-google-search": {
      "command": "npx",
      "args": [
        "mcp-google-search-mcp"
      ]
    }
  }
}

Use Google Search Tool MCP with multiple AI models

TypingMind connects MCP tools at the workspace level, so once Google Search Tool is connected, you can use it with different AI models in TypingMind instead of setting it up separately for each model. This MCP runs locally through the TypingMind MCP connector on your device.

Setup guide to use the local connector

Use this when the MCP server needs access to local files, apps, or private resources on your computer.

1

Open the MCP settings

In TypingMind, go to Settings, Advanced Settings, then Model Context Protocol and choose Setup Connector.

  1. Open TypingMind in your browser.
  2. Click the Settings icon.
  3. Go to Advanced Settings.
  4. Open the Model Context Protocol section.
  5. Click Setup Connector and choose This Device.
TypingMind MCP connector setup screen with This Device selected
2

Run the connector command

Choose This Device, copy the command from TypingMind, and run it in Terminal. Keep the process running while you use MCP.

  1. Copy the setup command shown by TypingMind.
  2. Open Terminal on macOS or Windows Terminal on Windows.
  3. Paste and run the command.
  4. Approve the package install if Terminal asks you to proceed.
  5. Keep the Terminal window running while using MCP tools.
3

Add Google Search Tool as a server

When the connector status is Ready, click Edit Servers and paste the MCP server configuration.

  1. Wait until the connector status shows Ready.
  2. Click Edit Servers.
  3. Paste the Google Search Tool MCP server configuration.
  4. Save the server list.
  5. Refresh if you want to confirm the connector is still ready.
TypingMind MCP settings showing active server and Edit Servers button
{
  "mcpServers": {
    "web-agent-master-google-search": {
      "command": "npx",
      "args": [
        "-y",
        "google-search-cli"
      ]
    }
  }
}
4

Use it across models

Save the server list, open Plugins, enable the Google Search Tool MCP tools, then select any supported AI model in TypingMind and use the tools in chat or assign them to an AI agent.

  1. Open the Plugins page in TypingMind.
  2. Enable the Google Search Tool MCP tools.
  3. Start a chat and choose the AI model you want to use.
  4. Use the MCP tools in chat or assign them to an AI agent.
  5. Switch to another AI model whenever needed without reconnecting MCP.
TypingMind chat using enabled MCP tools with a selected AI model
Can you use Google Search Tool to help me with this task?
Google Search Tool
Sure. I read it.
Here is what I found using Google Search Tool.

Frequently asked questions

What is the Google Search Tool MCP server used for?

Google Search Tool is an MCP server that lets compatible AI clients connect to external tools and context. In TypingMind, you can add this MCP server once and make its tools available in your AI workspace.

Can I use Google Search Tool MCP with multiple AI models in TypingMind?

Yes. TypingMind connects MCP tools at the workspace level, so you can use Google Search Tool with different AI models such as Claude, ChatGPT, Gemini, or other models you have configured in TypingMind without setting up the MCP server separately for each model.

Why use Google Search Tool MCP with TypingMind?

TypingMind is one of the best frontends for LLM chat because it brings multiple AI models, prompts, plugins, AI agents, API keys, and MCP tools into one workspace. With Google Search Tool connected, you can use its MCP tools across your preferred models while keeping your chat workflow organized in TypingMind.

How do I connect Google Search Tool MCP to TypingMind?

Google Search Tool runs through the TypingMind local MCP connector. This is best when the MCP server needs access to local files, desktop apps, command-line tools, or private resources on your computer.

What tools does Google Search Tool MCP provide in TypingMind?

Google Search Tool exposes MCP capabilities that can be enabled from the TypingMind Plugins page and used in chat or assigned to AI agents.

Do I need to share my API keys with TypingMind to use Google Search Tool MCP?

No. TypingMind is local-first and lets you keep your model providers, API keys, prompts, and MCP configuration under your control. If Google Search Tool requires authentication, add the required headers, OAuth settings, or local configuration for that MCP server when you create the connection.

Related MCP Servers

View all

Set up your own AI workspace now

Get notified about new features and future giveaways by subscribing to our newsletter 👇