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

Installation

Quick Setup (Recommended)

# Install the package globally
npm install -g @kyaniiii/google-search-mcp

# Run interactive setup
google-search-setup

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

git clone https://github.com/Fabien-desablens/google-search-mcp.git
cd google-search-mcp
npm install
npm run build
npm run setup

Uninstallation

Complete Removal

# Remove the package
npm uninstall -g @kyaniiii/google-search-mcp

# Remove from Claude Code
claude mcp remove google-search

# Remove configuration file (if desired)
npm run clean

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

{
  "keys": [
    {
      "id": "key_1",
      "apiKey": "AIzaSy...",
      "searchEngineId": "abc123...",
      "dailyUsage": 45,
      "dailyLimit": 100,
      "lastReset": "2024-07-30",
      "isActive": true
    }
  ],
  "lastUpdated": "2024-07-30T15:30:00Z",
  "version": "1.0.0"
}

⚠️ 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

Go to Google Cloud Console
Create a new project or select existing
Enable the "Custom Search API"

2. Generate API Key

Navigate to "APIs & Services" > "Credentials"
Click "Create Credentials" > "API Key"
Copy the generated key

3. Create Custom Search Engine

Visit Google Programmable Search Engine
Click "Get started" or "Add"
For "Sites to search", enter * to search the entire web
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:

User: "Search for latest AI news from this week"
Claude: I'll search for the latest AI news using Google Search...

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

{
  "query": "artificial intelligence news"
}

Advanced Search

{
  "query": "machine learning",
  "num": 10,
  "lr": "lang_en",
  "gl": "us",
  "dateRestrict": "m1",
  "fileType": "pdf"
}

Site-Specific Search

{
  "query": "typescript tutorial",
  "siteSearch": "stackoverflow.com",
  "siteSearchFilter": "i"
}

Quota Management

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

{
  "results": [...],
  "metadata": {
    "quotaStatus": {
      "totalUsed": 15,
      "totalLimit": 300,
      "keysStatus": [
        {
          "id": "key_1",
          "used": 15,
          "limit": 100,
          "remaining": 85,
          "active": true
        }
      ]
    }
  }
}

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

# Development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start server
npm start

# Setup configuration
npm run setup

Project Structure

google-search-mcp/
├── src/
│   ├── index.ts         # Entry point
│   ├── server.ts        # MCP server setup
│   ├── config.ts        # Configuration wrapper
│   ├── global-config.ts # Global config manager
│   └── tools/
│       └── search.ts    # Search implementation
├── build/               # Compiled JavaScript
├── setup.js             # Interactive setup tool
└── package.json

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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