Google Search MCP Server

A Model Context Protocol (MCP) server that provides Google Search functionality with automatic API key rotation and intelligent quota management.

Features

• Official Google Custom Search API integration

• Automatic API key rotation for increased daily limits

• Persistent quota tracking across sessions and directories

• Multi-language and geolocation support

• Advanced search filters (date, file type, site-specific)

• SafeSearch content filtering

• Global configuration - works from anywhere

• Compatible with Claude Desktop and other MCP clients

Related MCP server: Google API Discovery Service MCP Server

Installation

Quick Setup (Recommended)

This will:

• ✅ Configure your Google API keys interactively

• ✅ Set up global configuration file

• ✅ Automatically integrate with Claude Code

• ✅ Enable 100+ free searches per day per API key

Advanced Installation

Uninstallation

Complete Removal

Note: Configuration file (~/.google-search-mcp.json) is always preserved during updates and uninstallation to protect your API keys. Use npm run clean only if you want to completely remove your configuration.

Configuration

The setup tool creates a global configuration file at:

• Windows: %USERPROFILE%\.google-search-mcp.json

• Linux/macOS: ~/.google-search-mcp.json

This file contains:

• ✅ Your API keys and search engine IDs

• ✅ Persistent quota tracking (survives restarts)

• ✅ Automatic daily reset at midnight UTC

• ✅ Cross-directory usage (works from anywhere)

Example Configuration

⚠️ Important: If you manually edit the configuration file (~/.google-search-mcp.json), you must restart Claude Desktop for the changes to take effect.

Getting Google API Credentials

1. Create a Google Cloud Project

1. Go to Google Cloud Console

2. Create a new project or select existing

3. Enable the "Custom Search API"

2. Generate API Key

1. Navigate to "APIs & Services" > "Credentials"

2. Click "Create Credentials" > "API Key"

3. Copy the generated key

3. Create Custom Search Engine

1. Visit Google Programmable Search Engine

2. Click "Get started" or "Add"

3. For "Sites to search", enter * to search the entire web

4. Copy the Search Engine ID

4. Scale with Multiple Keys

• Each Google Cloud project provides 100 free searches/day

• Create multiple projects for more quota (e.g., 3 projects = 300 searches/day)

• The server automatically rotates between available keys

Usage with Claude Code

After running the setup, the server is automatically configured in Claude Code. You can immediately use it:

The server exposes a google_search tool with these parameters:

Required Parameters

• query (string): Search query

Optional Parameters

• num (number): Number of results (1-10, default: 5)

• start (number): Starting index for results

• safe (string): SafeSearch level ('off', 'active')

• lr (string): Language restriction (e.g., 'lang_en', 'lang_fr')

• gl (string): Geolocation (country code: 'us', 'fr', 'uk')

• dateRestrict (string): Time period ('d1', 'w1', 'm1', 'y1')

• fileType (string): File type filter ('pdf', 'doc', 'ppt')

• siteSearch (string): Search specific site

• siteSearchFilter (string): Include ('i') or exclude ('e') site

• cr (string): Country restriction ('countryUS', 'countryFR')

• exactTerms (string): Exact phrase to include

• excludeTerms (string): Terms to exclude

• orTerms (string): Alternative terms (OR search)

• sort (string): Sort by date ('date')

• searchType (string): Search type ('image' for image search)

Examples

Basic Search

Advanced Search

Site-Specific Search

Quota Management

The server provides real-time quota information in each response:

Quota Features

• Automatic daily reset at midnight UTC

• Intelligent key rotation when limits are reached

• Disabled keys automatically reactivate after reset

• Persistent tracking across server restarts

• No charges - stops at free tier limits

Error Handling

The server gracefully handles various error scenarios:

• Quota Exceeded: Automatically rotates to next available key

• All Keys Exhausted: Returns clear error message with quota status

• Invalid API Key: Disables the key and continues with others

• Network Errors: Returns detailed error information

Development

Prerequisites

• Node.js 18+

• TypeScript

• Google Cloud account

Scripts

Project Structure

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues, questions, or contributions, please visit: https://github.com/Fabien-desablens/google-search-mcp