Enhanced Google Search MCP Server
⚠️ EXPERIMENTAL PROJECT - USE AT YOUR OWN RISK
This is an experimental Google search MCP server that uses web scraping techniques. Please be aware of the following:
- Rate Limiting: Google may block or rate-limit requests from this server
- Reliability: Search results may be inconsistent due to Google's anti-scraping measures
🔍 RECOMMENDED ALTERNATIVES
For production use, we strongly recommend using official search APIs or established MCP servers:
- DuckDuckGo MCP Servers: More reliable and ToS-compliant alternatives
- Bing Search API: Microsoft's official search API with MCP integration
- Google Custom Search API: Google's official search API (requires API key)
- SearXNG MCP: Privacy-focused meta-search engine integration
Use this experimental server only if you understand the risks and limitations.
A powerful Model Context Protocol (MCP) server that provides enhanced Google search capabilities with advanced anonymization and anti-detection features.
Features
🔍 Enhanced Search Capabilities
- Advanced Query Support: Handle complex search queries with quotes, operators, and filters
- Configurable Results: Limit results (1-10), set language, region, safe search, and time range
- Multiple Parsing Strategies: Robust result extraction with fallback mechanisms
🛡️ Advanced Anonymization
- Realistic Browser Fingerprinting: Rotating user agents that mimic real browsers (Chrome, Firefox, Safari, Edge)
- Dynamic Headers: Randomized Accept-Language, Accept-Encoding, and security headers
- Session Randomization: Unique session IDs and request fingerprints
- Request Timing: Random delays to avoid detection patterns
🚀 Reliability Features
- Smart Retry Logic: Exponential backoff with jitter for failed requests
- Rate Limit Handling: Automatic detection and graceful handling of rate limits
- Error Recovery: Comprehensive error handling with user-friendly messages
- Timeout Management: Configurable timeouts with proper error reporting
🔧 Technical Improvements
- Multiple Result Selectors: Adapts to Google's changing HTML structure
- URL Cleaning: Proper handling of Google's redirect URLs
- Content Validation: Ensures all results have valid URLs and content
- Comprehensive Logging: Detailed logging for debugging and monitoring
Installation
Installing via Smithery
To install google-search-mcp for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @kongyo2/google-search-mcp --client claude
Manual Installation
npm install
Usage
Development Mode
Start the server in development mode with interactive CLI:
npm run dev
Production Mode
Start the server for production use:
npm run start
Testing
Run the comprehensive test suite:
npm run test
For continuous testing during development:
npm run test:watch
MCP Tool: search
The server provides a single, powerful search tool with the following parameters:
Parameters
query(required): Search query to executelimit(optional): Maximum number of results (1-10, default: 5)language(optional): Language code (e.g., 'en', 'es', 'fr', 'de', 'ja')region(optional): Region code (e.g., 'us', 'uk', 'ca', 'au')safeSearch(optional): Filter level ('off', 'moderate', 'strict')timeRange(optional): Time filter ('hour', 'day', 'week', 'month', 'year')
Example Usage
{
"name": "search",
"arguments": {
"query": "Model Context Protocol MCP",
"limit": 5,
"language": "en",
"region": "us",
"safeSearch": "moderate",
"timeRange": "week"
}
}
Configuration with Claude Desktop
Add this configuration to your Claude Desktop MCP settings:
{
"mcpServers": {
"enhanced-google-search": {
"command": "npx",
"args": ["tsx", "/path/to/your/project/src/server.ts"]
}
}
}
Architecture
Core Components
- UserAgentGenerator: Creates realistic browser fingerprints
- RequestAnonymizer: Handles request anonymization and timing
- SearchParameterBuilder: Constructs optimized search parameters
- ResultParser: Robust HTML parsing with multiple strategies
Anti-Detection Features
- Browser Fingerprint Rotation: Cycles through realistic user agents
- Header Randomization: Varies request headers to avoid patterns
- Timing Randomization: Adds random delays between requests
- Session Management: Generates unique session identifiers
- Parameter Variation: Adds random search parameters
Error Handling
The server provides comprehensive error handling for:
- Rate limiting by Google
- Network timeouts and connectivity issues
- Access denied/blocked requests
- Invalid or empty responses
- Parsing failures with fallback strategies
Development
Project Structure
src/
├── server.ts # Main MCP server implementation
├── search.ts # Enhanced search functionality
├── search.test.ts # Comprehensive test suite
└── types.ts # TypeScript type definitions
Code Quality
The project includes:
- TypeScript: Full type safety and IntelliSense support
- ESLint: Code linting with TypeScript rules
- Prettier: Consistent code formatting
- Vitest: Fast and reliable testing framework
Scripts
npm run build: Compile TypeScript to JavaScriptnpm run start: Start the server in production modenpm run dev: Start in development mode with CLInpm run test: Run the test suitenpm run test:watch: Run tests in watch modenpm run lint: Check code quality and typesnpm run format: Format code with Prettier
Testing
The test suite covers:
- Basic search functionality
- Parameter validation and handling
- Language and region filtering
- Safe search and time range filters
- Complex query handling
- Error scenarios and edge cases
- URL validation and result formatting
All tests use real Google search requests to ensure functionality works in practice.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Run
npm run lintandnpm run test - Submit a pull request
License
MIT License - see LICENSE file for details.