# Gemini MCP Server with Google Search Grounding

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
[![Gemini](https://img.shields.io/badge/Gemini-2.5%20Pro-blue.svg)](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/gemini)

## Overview

A production-ready MCP (Model Context Protocol) server that integrates Google's Gemini 2.5 Pro with real-time Google Search grounding capabilities. This minimal implementation provides current information retrieval through a single, powerful tool designed for seamless integration with MCP clients.

## Features

- **Real-time Information**: Access current information via Google Search grounding
- **Gemini 2.5 Pro Integration**: Leverage Google's most capable AI model
- **Automatic Date Context**: Dynamically includes today's date in all queries
- **Zero-bloat Architecture**: Just 121 lines of code, 2 dependencies, no build process
- **Professional MCP Protocol**: Full compliance with MCP JSON-RPC over stdio
- **Production Ready**: Comprehensive error handling and Google Cloud ADC authentication
- **Live Tested**: Successfully tested with current news queries returning accurate, up-to-date information

## Prerequisites

- Node.js 18.0.0 or higher
- Google Cloud Project with Vertex AI API enabled
- Google Cloud CLI (gcloud) installed
- npm or yarn package manager

## Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/jaysm03/gemini-grounded-search
   cd gemini-grounded-search
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Configure Google Cloud**
   ```bash
   # Set your Google Cloud project
   export GOOGLE_CLOUD_PROJECT="your-project-id"
   
   # Authenticate (creates Application Default Credentials)
   gcloud auth application-default login
   ```

4. **Optional: Create .env file**
   ```bash
   cp .env.example .env
   # Edit .env and add your Google Cloud project ID
   ```

5. **Verify installation**
   ```bash
   node index.js
   ```
   Expected output: `Gemini MCP server running`

## MCP Settings Configuration

### Environment Variables

Create a `.env` file in the project root:

```env
GOOGLE_CLOUD_PROJECT=your-project-id-here
# Optional: GOOGLE_CLOUD_LOCATION=us-central1
```

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `GOOGLE_CLOUD_PROJECT` | Yes | - | Your Google Cloud project ID |
| `GOOGLE_CLOUD_LOCATION` | No | `us-central1` | Vertex AI location |

### MCP Client Configuration

The MCP server operates on-demand and is automatically started by MCP clients when needed. Configure your MCP client with the following settings:

#### For Roo/Cline (VS Code)

**Configuration File Locations:**
- **macOS**: `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`
- **Windows**: `%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json`
- **Linux**: `~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`

**Complete Configuration:**
```json
{
  "mcpServers": {
    "gemini-grounded-search": {
      "command": "node",
      "args": [
        "/absolute/path/to/gemini-grounded-search/index.js"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id"
      },
      "alwaysAllow": [
        "grounded_search"
      ],
      "timeout": 3600
    }
  }
}
```

#### For Claude Desktop

**Configuration File Locations:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

**Complete Configuration:**
```json
{
  "mcpServers": {
    "gemini-grounded-search": {
      "command": "node",
      "args": ["/absolute/path/to/gemini-grounded-search/index.js"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id"
      },
      "alwaysAllow": [
        "grounded_search"
      ]
    }
  }
}
```

**Important Configuration Notes:**
- Replace `/absolute/path/to/gemini-grounded-search/` with the actual absolute path to your project directory
- Replace `your-project-id` with your actual Google Cloud project ID
- Use forward slashes (/) in paths, even on Windows
- The `timeout` parameter is optional and defaults to system settings
- Restart your MCP client after configuration changes

## Usage

### Available Tool

**`grounded_search`** - Search for current information using Gemini with Google Search grounding

**Parameters:**
- `query` (string, required): Search query for current information

### Usage Examples

#### Basic Search
```json
{
  "method": "tools/call",
  "params": {
    "name": "grounded_search",
    "arguments": {
      "query": "latest AI developments in 2025"
    }
  }
}
```

#### Current Events Query
```json
{
  "method": "tools/call",
  "params": {
    "name": "grounded_search",
    "arguments": {
      "query": "recent breakthroughs in quantum computing"
    }
  }
}
```

#### Technical Information
```json
{
  "method": "tools/call",
  "params": {
    "name": "grounded_search",
    "arguments": {
      "query": "Node.js 22 new features and release date"
    }
  }
}
```

### Response Format

```
Today's date: 2025-10-25
Query: [your query]

[Comprehensive response with current information from Google Search grounding]
```

## Model Information

### Gemini 2.5 Pro

This server uses **Gemini 2.5 Pro**, Google's most capable AI model with the following characteristics:

- **Advanced Reasoning**: Superior analytical and problem-solving capabilities
- **Google Search Grounding**: Real-time access to current information via Google Search
- **Large Context Window**: Handles complex queries with extensive context
- **Multimodal Understanding**: Processes and understands various types of information
- **Production Ready**: Enterprise-grade reliability and performance

### When to Use This Server

- **Current Information**: When you need up-to-date information that may not be in the model's training data
- **Real-time Data**: For queries about recent events, news, or developments
- **Fact Verification**: To verify information against current web sources
- **Research Tasks**: For comprehensive research requiring multiple current sources
- **Dynamic Content**: When information changes frequently (weather, stock prices, news)

## Google Cloud Setup

### 1. Create/Select Google Cloud Project

```bash
gcloud projects create your-project-id
gcloud config set project your-project-id
```

### 2. Enable Vertex AI API

```bash
gcloud services enable aiplatform.googleapis.com
```

### 3. Set up Authentication

```bash
gcloud auth application-default login
```

This creates Application Default Credentials (ADC) that the server uses for authentication.

## Deployment

### Production Deployment Considerations

**Security:**
- Secure Google Cloud credentials using Application Default Credentials
- Implement rate limiting to prevent abuse
- Use HTTPS for all external communications
- Regular security audits and dependency updates
- Restrict API access to authorized users only

**Monitoring:**
- Monitor Google Cloud API usage and quotas
- Track response times and performance metrics
- Set up error tracking and alerting systems
- Implement comprehensive logging for debugging

**Scalability:**
- The server supports horizontal scaling through multiple instances
- Implement load balancing for high-availability deployments
- Monitor resource usage and optimize as needed
- Consider caching for frequently requested information

**Environment Setup:**
- Use process managers like PM2 for production deployments
- Configure proper environment variables for different stages
- Implement health checks and automatic restarts
- Set up backup and recovery procedures

### Server Operation

The MCP server operates on-demand:
- Automatically started by MCP clients when needed
- Shuts down when not in use to conserve resources
- No manual server management required
- Supports concurrent requests from multiple clients

## Troubleshooting

### Common Issues

**1. "GOOGLE_CLOUD_PROJECT environment variable is required"**

```bash
export GOOGLE_CLOUD_PROJECT="your-project-id"
```

Or add to your `.env` file:
```env
GOOGLE_CLOUD_PROJECT=your-project-id
```

**2. "Failed to initialize Gemini client"**

- Ensure Vertex AI API is enabled:
  ```bash
  gcloud services enable aiplatform.googleapis.com
  ```
- Check authentication:
  ```bash
  gcloud auth application-default login
  ```
- Verify project ID is correct:
  ```bash
  gcloud config get-value project
  ```

**3. "Gemini API error: Permission denied"**

- Ensure your account has Vertex AI User role
- Check project billing is enabled in Google Cloud Console
- Verify API quotas are not exceeded

**4. MCP client can't connect**

- Verify the absolute path to `index.js` in MCP configuration
- Check Node.js version (requires 18+):
  ```bash
  node --version
  ```
- Ensure `GOOGLE_CLOUD_PROJECT` is set in MCP config
- Restart your MCP client after configuration changes

### Authentication Issues

**Verify ADC Setup:**
```bash
gcloud auth application-default print-access-token
```

**Check Current Project:**
```bash
gcloud config list
```

**Test API Connectivity:**
```bash
gcloud ai models list --region=us-central1
```

### Configuration Problems

**Path Issues:**
- Use absolute paths in configuration files
- Avoid using `~` or environment variables in paths
- Use forward slashes (/) even on Windows

**Permission Errors:**
- Ensure proper file permissions for the project directory
- Check that Node.js has execute permissions on `index.js`

**Network Issues:**
- Check firewall settings and network connectivity
- Verify Google Cloud API endpoints are accessible
- Ensure no proxy issues blocking API calls

### Debug Mode

Run with error logging:
```bash
GOOGLE_CLOUD_PROJECT=your-project-id node index.js 2>&1 | tee debug.log
```

Check server startup:
```bash
node index.js
# Should output: "Gemini MCP server running"
```

### Support

For issues:
1. Check Google Cloud Console for API quotas and billing
2. Verify MCP client logs for connection errors
3. Test authentication: `gcloud auth application-default print-access-token`
4. Review [Google Cloud Vertex AI documentation](https://cloud.google.com/vertex-ai/docs)
5. Check [MCP Protocol documentation](https://modelcontextprotocol.io/)

## Project Structure

```
gemini-grounded-search/
├── package.json           # Dependencies and metadata
├── package-lock.json      # Dependency lock file
├── index.js              # Complete MCP server (121 lines)
├── .env.example          # Environment variable template
├── .env                  # Environment variables (create from .env.example)
├── .gitignore            # Git ignore rules
├── LICENSE               # MIT License
├── CHANGELOG.md          # Version history
├── README.md             # This file
├── node_modules/         # Dependencies
└── docs/                 # Additional documentation
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

---

**Current Version**: 1.0.0  
**Release Date**: 2025-10-25  
**Node.js**: 18+  
**MCP Protocol**: 1.0.1  
**Model**: Gemini 2.5 Pro with Google Search Grounding