google-context-mcp/README.md

Secure Google Search MCP server providing real-time coding context to AI models and LLMs - find latest docs, solutions, and best practices while coding

# Google Context MCP

A secure and user-friendly Google Search MCP (Model Context Protocol) server that provides **real-time coding context** to AI models and LLMs. **Your API keys are never exposed or stored in the package - they're securely stored on your local machine.**

## 🎯 **Perfect for Coding & Development**

This tool helps AI assistants and LLMs find **latest documentation**, **recent solutions**, and **current best practices** while you're coding. Instead of outdated training data, get real-time information from the web!

### **What This Enables:**
- 🔍 **Find latest API documentation** for any library or framework
- 🐛 **Search for recent bug fixes** and solutions
- 📚 **Get current tutorials** and examples
- 🆕 **Discover new features** and updates
- 💡 **Find alternative approaches** to coding problems

## 🚀 Quick Start

```bash
# Install and run the setup wizard
npx google-context-mcp setup

# Perform a search
npx google-context-mcp search "your search query"

# Test the functionality
npx google-context-mcp test
```

## 🔐 Security Features

- **No exposed API keys**: Your Google API credentials are stored locally in your home directory
- **Interactive setup**: Guided wizard to configure your credentials securely
- **Local configuration**: All settings stored in `~/.google-context-mcp.json`
- **No telemetry**: Your search queries and API usage remain private

## 📋 Prerequisites

Before using this package, you'll need:

1. **Google Cloud Project** with Custom Search API enabled
2. **API Key** for the Custom Search API
3. **Custom Search Engine ID** from Google's Programmable Search Engine

### Setting up Google Cloud Project

1. Visit [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the **Custom Search API**
4. Create credentials (API Key) for the Custom Search API
5. Set up billing (required for API usage)

### Creating a Custom Search Engine

1. Visit [Programmable Search Engine](https://programmablesearchengine.google.com/)
2. Click "Create a search engine"
3. Enter the sites you want to search (or leave blank for web-wide search)
4. Copy your Search Engine ID (cx parameter)

## 🛠️ Installation & Setup

### Option 1: One-time setup (Recommended)

```bash
# Run the interactive setup wizard
npx google-context-mcp setup
```

The wizard will guide you through:
- Entering your Google API key
- Providing your Custom Search Engine ID
- Setting optional defaults (language, country, safe search, etc.)

### Option 2: Manual configuration

Create a configuration file at `~/.google-context-mcp.json`:

```json
{
  "googleApiKey": "your_api_key_here",
  "customSearchEngineId": "your_search_engine_id_here",
  "defaultLanguage": "en",
  "defaultCountry": "US",
  "defaultSafeSearch": "medium",
  "defaultNumResults": 5
}
```

## 🎯 MCP (Model Context Protocol) Integration

### For Cursor Users

To integrate with Cursor and use Google Search directly in your AI conversations:

1. **Create MCP configuration file** at `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "google-search": {
      "command": "npx",
      "args": ["google-context-mcp", "mcp-server"],
      "env": {}
    }
  }
}
```

2. **Restart Cursor** to load the MCP configuration
3. **Use Google Search in Cursor** for coding help:
   - "Search for latest React 18 hooks documentation"
   - "Find recent solutions for TypeScript generic constraints"
   - "Search for current best practices in Python async programming"
   - "Find latest Next.js 14 app router examples"

### For Other MCP-Compatible Tools

Add this configuration to your tool's MCP settings:

```json
{
  "mcpServers": {
    "google-search": {
      "command": "npx",
      "args": ["google-context-mcp", "mcp-server"],
      "env": {}
    }
  }
}
```

## 📖 Usage

### Basic Search

```bash
npx google-context-mcp search "artificial intelligence"
```

### Advanced Search Options

```bash
# Search with specific options
npx google-context-mcp search "machine learning" \
  --num-results 10 \
  --language en \
  --country US \
  --safe-search high \
  --site "github.com"

# Date-restricted search
npx google-context-mcp search "latest news" --date-restrict d1
```

### Available Commands

| Command | Description |
|---------|-------------|
| `setup` | Interactive setup wizard for credentials |
| `search <query>` | Perform a Google search |
| `test` | Test your configuration |
| `info` | Show current configuration |
| `reset` | Remove all saved credentials |
| `mcp-server` | Start MCP server for integration |

### Search Options

| Option | Description | Default |
|--------|-------------|---------|
| `-n, --num-results` | Number of results (1-10) | 5 |
| `-l, --language` | Language code (e.g., en, es, fr) | - |
| `-c, --country` | Country code (e.g., US, GB, IN) | - |
| `-s, --safe-search` | Safe search level (off/medium/high) | medium |
| `-d, --date-restrict` | Date restriction (d1, w1, m1, y1) | - |
| `--site` | Restrict to specific domain | - |

## 🔧 Configuration

### Configuration File Location

Your configuration is stored at: `~/.google-context-mcp.json`

### Environment Variables (Alternative)

You can also use environment variables instead of the config file:

```bash
export GOOGLE_API_KEY="your_api_key"
export GOOGLE_CUSTOM_SEARCH_ENGINE_ID="your_search_engine_id"
```

### Updating Configuration

```bash
# Re-run setup to update credentials
npx google-context-mcp setup

# Or manually edit the config file
nano ~/.google-context-mcp.json
```

## 🚨 Troubleshooting

### Common Issues

**"No valid credentials found"**
```bash
# Run the setup wizard
npx google-context-mcp setup
```

**"API key is invalid or quota exceeded"**
- Check your API key in Google Cloud Console
- Verify billing is enabled
- Check API usage quotas

**"Custom Search Engine ID is required"**
- Create a custom search engine at [Programmable Search Engine](https://programmablesearchengine.google.com/)
- Copy the Search Engine ID (cx parameter)

**"Rate limit exceeded"**
- Wait a few minutes before trying again
- Check your API quota limits in Google Cloud Console

### Reset Configuration

```bash
# Remove all saved credentials
npx google-context-mcp reset

# Then run setup again
npx google-context-mcp setup
```

## 💰 Pricing & Quotas

- **Google Custom Search API**: 100 free queries per day
- **Additional queries**: $5 per 1000 queries
- **No charges from this package**: You only pay Google for API usage

## 🔒 Privacy & Security

- **Local storage**: All credentials stored on your machine only
- **No logging**: Search queries are not logged or stored
- **Direct API calls**: All requests go directly to Google's servers
- **No third-party access**: Your API keys never leave your machine

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## ⚠️ Disclaimer

This package is not affiliated with Google. It's an open-source tool that uses Google's Custom Search API. Users are responsible for complying with Google's API terms of service and usage policies.

## 🆘 Support

If you encounter any issues:

1. Check the troubleshooting section above
2. Verify your Google Cloud Project and API setup
3. Ensure your credentials are correctly configured
4. Check the [Google Custom Search API documentation](https://developers.google.com/custom-search/v1/introduction)

---

**Made with ❤️ for the AI/LLM community**