Submit
Fabien-desablens

Google Search MCP Server

Community Fabien-desablens
Updated

MCP server for Google Search with automatic API key rotation and quota management

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

  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:

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:

  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

MCP Server · Populars

MCP Server · New