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 execute
limit (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 JavaScript
npm run start: Start the server in production mode
npm run dev: Start in development mode with CLI
npm run test: Run the test suite
npm run test:watch: Run tests in watch mode
npm run lint: Check code quality and types
npm 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 lint and npm run test
Submit a pull request

License

MIT License - see LICENSE file for details.