Gemini Grounded Search

License: MIT Node.js 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

   git clone https://github.com/jaysm03/gemini-grounded-search
   cd gemini-grounded-search
   

2. Install dependencies

   npm install
   

3. Configure Google Cloud

   # 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

   cp .env.example .env
   # Edit .env and add your Google Cloud project ID
   

5. Verify installation

   node index.js
   

   Expected output: Gemini MCP server running

MCP Settings Configuration

Environment Variables

Create a .env file in the project root:

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:

{
  "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:

{
  "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

{
  "method": "tools/call",
  "params": {
    "name": "grounded_search",
    "arguments": {
      "query": "latest AI developments in 2025"
    }
  }
}

Current Events Query

{
  "method": "tools/call",
  "params": {
    "name": "grounded_search",
    "arguments": {
      "query": "recent breakthroughs in quantum computing"
    }
  }
}

Technical Information

{
  "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

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

2. Enable Vertex AI API

gcloud services enable aiplatform.googleapis.com

3. Set up Authentication

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"

export GOOGLE_CLOUD_PROJECT="your-project-id"

Or add to your .env file:

GOOGLE_CLOUD_PROJECT=your-project-id

2. "Failed to initialize Gemini client"

• Ensure Vertex AI API is enabled:

  gcloud services enable aiplatform.googleapis.com
  

• Check authentication:

  gcloud auth application-default login
  

• Verify project ID is correct:

  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+):

  node --version
  

• Ensure GOOGLE_CLOUD_PROJECT is set in MCP config
• Restart your MCP client after configuration changes

Authentication Issues

Verify ADC Setup:

gcloud auth application-default print-access-token

Check Current Project:

gcloud config list

Test API Connectivity:

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:

GOOGLE_CLOUD_PROJECT=your-project-id node index.js 2>&1 | tee debug.log

Check server startup:

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
5. Check MCP Protocol documentation

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 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