README.md•7.04 kB
# 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)
```bash
# 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
```bash
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
```bash
# 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
```json
{
"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](https://console.cloud.google.com/)
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](https://programmablesearchengine.google.com/)
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
```json
{
"query": "artificial intelligence news"
}
```
### Advanced Search
```json
{
"query": "machine learning",
"num": 10,
"lr": "lang_en",
"gl": "us",
"dateRestrict": "m1",
"fileType": "pdf"
}
```
### Site-Specific Search
```json
{
"query": "typescript tutorial",
"siteSearch": "stackoverflow.com",
"siteSearchFilter": "i"
}
```
## Quota Management
The server provides real-time quota information in each response:
```json
{
"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
```bash
# 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