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 resultssafe
(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 sitesiteSearchFilter
(string): Include ('i') or exclude ('e') sitecr
(string): Country restriction ('countryUS', 'countryFR')exactTerms
(string): Exact phrase to includeexcludeTerms
(string): Terms to excludeorTerms
(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