Provides real-time Google search capabilities with anti-bot protection, returning search results with titles, links, and snippets, plus optional raw HTML extraction for analysis
Google Search Tool
A Playwright-based Python 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.
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
Python Native: Built with Python for better performance and easier deployment
Technical Features
Developed with Python 3.8+, providing excellent performance and wide compatibility
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
Anti-bot protection mechanisms at multiple levels
Installation
Usage
Command Line Tool
MCP Server
Command Line Options
-l, --limit <number>
: Result count limit (default: 10)-t, --timeout <number>
: Timeout time in milliseconds (default: 30000)--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
: Get raw HTML of search result page instead of parsed results--save-html
: Save HTML to file (use with --get-html)--html-output <path>
: Specify HTML output file path (use with --get-html and --save-html)-V, --version
: Show version number-h, --help
: Show help information
Output Example
HTML Output Example
When using the --get-html
option, the output will contain HTML content-related information:
If you also use the --save-html
option, the output will also include the HTML saved file path:
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 securely access external tools and data.
Integration with Claude Desktop
Edit 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 enter
%APPDATA%\Claude
in Windows Explorer address bar to access directly
Add server configuration and restart Claude
After integration, you can directly use search functionality in Claude, such as "Search for the latest AI research".
Project Structure
Technology Stack
Python 3.8+: Development language, providing excellent performance and compatibility
Playwright: For browser automation, supporting multiple browsers
MCP SDK: For implementing MCP server development tools
asyncio: Python's standard library for asynchronous I/O
aiofiles: Asynchronous file operations
Development Guide
All commands can be run in the project root directory:
Error Handling
The tool has built-in robust error handling mechanisms:
Provides friendly error information when browser startup fails
Automatically returns error status when network connection issues occur
Provides detailed logs when search result parsing fails
Gracefully exits and returns useful information 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
Don't send requests too frequently to avoid being blocked by Google
Some regions may require proxies to access Google
Playwright requires browser installation, which will be automatically downloaded on first use
State Files
State files contain browser cookies and storage data, please keep them safe
Using state files can effectively avoid Google's anti-bot detection and improve search success rate
MCP Server
When using MCP server, please ensure Claude Desktop is updated to the latest version
When configuring Claude Desktop, please use absolute paths pointing to MCP server files
Windows Environment Special Notes
In Windows environment, first run may require administrator privileges to install Playwright browsers
If you encounter permission issues, try running Command Prompt or PowerShell as administrator
Windows Firewall may block Playwright browser network connections, please allow access when prompted
Browser state files are saved by default in the user's home directory under
.google-search-browser-state.json
Log files are saved in the system temporary directory under
google-search-logs
folder
Comparison with Commercial SERP APIs
Compared to paid search engine results API services (such as SerpAPI), this project provides the following advantages:
Completely Free: No API call fees required
Local Execution: All searches are executed locally, no dependency on third-party services
Privacy Protection: Search queries are not recorded by third parties
Customizability: Completely open source, can be modified and extended as needed
No Usage Restrictions: Not subject to API call count or frequency limitations
MCP Integration: Native support for integration with AI assistants like Claude
Anti-Bot Protection
This project implements multiple layers of anti-bot protection:
Client Level Protection
Request interval control with random delays
Timeout protection for tool calls
Intelligent error handling
Server Level Protection
Request frequency limiting
Random delays between requests
Global request counting and management
Search Level Protection
Browser fingerprint randomization
Device and locale randomization
Browser state management
Automatic CAPTCHA detection and handling
Performance
Response Time: Typically 5-15 seconds
Success Rate: 95%+ (with state files)
Concurrency: Supports asynchronous operations
Memory Usage: Optimized with cleanup after each call
Stability: Robust error recovery and timeout handling
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Enables AI assistants to perform real-time Google searches with anti-bot protection. Bypasses search engine restrictions using advanced browser automation to extract search results locally without requiring paid API services.
Related MCP Servers
- AsecurityAlicenseAqualityEnables search capabilities using a Google Custom Search Engine, allowing users to input a search term and retrieve search result titles, links, and snippets, while facilitating integration with other tools for content extraction and advanced search strategies.Last updated -128The Unlicense
- AsecurityFlicenseAqualityEnables free web searching using Google search results with no API keys required, returning structured results with titles, URLs, and descriptions.Last updated -1173
- AsecurityFlicenseAqualityA Playwright-based tool that performs Google searches and extracts results while bypassing anti-bot mechanisms, providing real-time search capabilities for AI assistants.Last updated -1592
- -securityFlicense-qualityEnables searching for AI agents by keywords or categories, allowing users to discover tools like coding agents, GUI agents, or industry-specific assistants across marketplaces.Last updated -40