gemini-grounded-search by jaysm03 - MCP Server

Gemini MCP Server with Google Search Grounding

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

Clone the repository

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

Install dependencies
```
npm install
```

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

Optional: Create .env file

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

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:

Check Google Cloud Console for API quotas and billing
Verify MCP client logs for connection errors
Test authentication: gcloud auth application-default print-access-token
Review Google Cloud Vertex AI documentation
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 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