Google Search

🚀 Google Search Tool Usage Guide

This guide provides a comprehensive overview of how to install, use, and maintain the Google Search Tool, along with important considerations and error handling mechanisms.

📦 Installation

Run the following commands in the project root directory:

# Install dependencies
pnpm install

# Install Playwright browsers
pnpm run postinstall

# Compile TypeScript code
pnpm build

# Clean up compiled output
pnpm clean

💻 Usage Examples

All commands can be run in the project root directory:

Basic Usage

# Run in development mode
pnpm dev "search keyword"

# Run in debug mode (show browser interface)
pnpm debug "search keyword"

# Run the compiled code
pnpm start "search keyword"

# Test the search functionality
pnpm test

Advanced Usage

# Run the MCP server in development mode
pnpm mcp

# Run the compiled MCP server
pnpm mcp:build

🔧 Error Handling

The tool comes with a robust error handling mechanism:

• Displays friendly error messages when the browser fails to start.
• Automatically returns an error status for network connection issues.
• Records detailed logs when search result parsing fails.
• Gracefully exits and provides useful information in case of timeouts.

⚠️ Important Notes

General Notes

• This tool is for learning and research purposes only.
• Please comply with Google's terms of service and policies.
• Avoid sending frequent requests to prevent being blocked by Google.
• A proxy may be required to access Google in some regions.
• Playwright will automatically download browsers, which may consume bandwidth on first use.

State File Notes

• The state file contains browser cookies and storage data. Please keep it secure.
• Using the state file can effectively bypass Google's anti-bot detection and improve search success rates.

MCP Server Notes

• The MCP server requires Node.js v16 or higher.
• Ensure you use the latest version when configuring the Claude desktop client.
• Use the absolute path of the MCP service file when configuring Claude Desktop.

Windows-specific Notes

• Administrator privileges may be required to install Playwright browsers on Windows.
• If you encounter permission issues, try running the command prompt or PowerShell as an administrator.
• The Windows firewall may block network connections for Playwright browsers. Allow access when prompted.
• The browser state file is saved by default in the user's home directory as .google-search-browser-state.json.
• Log files are stored in the google-search-logs folder in the system's temporary directory.

📊 Comparison with Commercial SERP APIs

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