Google AI Search MCP

This project implements a Model Context Protocol (MCP) server that provides a comprehensive suite of Google AI-powered search and documentation tools specifically designed to help AI coders overcome LLM knowledge gaps and information limitations.

Implementation notes

Provider selection and credentials are resolved at runtime, so a tool being listed does not prove that its upstream provider is configured or reachable. Treat model-produced comparisons, architecture guidance, and security analysis as material to verify against the cited primary sources rather than deterministic findings.

For a source-linked comparison of the design pressures across this project and six other public MCP implementations, see What building seven MCP servers taught me about production MCP.

Features

• Provides access to Google AI models (Vertex AI and Gemini API) via specialized MCP tools.
• Focuses on real-time information retrieval and documentation-based analysis.
• Supports web search grounding for current information that LLMs lack.
• Configurable model ID, temperature, streaming behavior, max output tokens, and retry settings via environment variables.
• Uses streaming API by default for potentially better responsiveness.
• Includes basic retry logic for transient API errors.
• Minimal safety filters applied (BLOCK_NONE) to reduce potential blocking (use with caution).

Tools Provided

Core Search & Documentation Tools

• answer_query_websearch: Developer-focused natural language queries with automatic technical detection, enhanced search methodology, and comprehensive code formatting using Google AI with real-time search results.
• explain_topic_with_docs: Streamlined technical explanations with improved debugging scenarios, synthesizing information from official documentation with reduced verbosity and enhanced troubleshooting guidance.
• get_doc_snippets: Enhanced code snippet retrieval with progressive complexity examples, advanced search patterns, version-specific targeting, and comprehensive context for technical queries from official documentation.
• generate_project_guidelines: Generates comprehensive structured project guidelines documents based on specified technologies, using web search for current best practices and industry standards.

Advanced Analysis Tools

• code_analysis_with_docs: Evidence-based code analysis with standardized citations, severity categorization, and actionable recommendations by comparing code against official documentation best practices.
• technical_comparison: Produces technology comparisons across requested criteria using current search context where available. Verify quantitative or market claims against the cited primary sources.
• architecture_pattern_recommendation: Produces architecture options, tradeoffs, and implementation considerations for a described use case. Validate the recommendation against the system's actual constraints before adopting it.

(Note: Input/output schemas for each tool are defined in their respective files within src/tools/ and exposed via the MCP server.)

Prerequisites

• Node.js (v18+)
• Bun (npm install -g bun)
• Google Cloud Project with Billing enabled (if using Vertex AI).
• Vertex AI API enabled in the GCP project (if using Vertex AI).
• Google Cloud Authentication configured in your environment (Application Default Credentials via gcloud auth application-default login is recommended, or a Service Account Key) OR Gemini API key.

Setup & Installation

1. Clone/Place Project: Ensure the project files are in your desired location.
2. Install Dependencies:
   bash

   Copy

   bun install
   

3. Configure Environment:
   • Create a .env file in the project root (copy .env.example).
   • Set the required and optional environment variables as described in .env.example.
     • Set AI_PROVIDER to either "vertex" or "gemini".
     • If AI_PROVIDER="vertex", GOOGLE_CLOUD_PROJECT is required.
     • If AI_PROVIDER="gemini", GEMINI_API_KEY is required.
4. Build the Server:
   bash

   Copy

   bun run build
   

   This compiles the TypeScript code to build/index.js.

Usage (Standalone / NPX)

The package is published to npm and can be run directly with npx:

# Ensure required environment variables are set (e.g., GOOGLE_CLOUD_PROJECT or GEMINI_API_KEY)
bunx google-ai-search-mcp

Alternatively, install it globally:

bun install -g google-ai-search-mcp
# Then run:
google-ai-search-mcp

Note: Running standalone requires setting necessary environment variables (like GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, GEMINI_API_KEY, authentication credentials if not using ADC) in your shell environment before executing the command.

Docker

Build the local container image:

docker build -t google-ai-search-mcp .

Run with the Gemini API provider:

docker run --rm -i \
  -e AI_PROVIDER=gemini \
  -e GEMINI_API_KEY \
  google-ai-search-mcp

For Vertex AI, pass AI_PROVIDER=vertex, GOOGLE_CLOUD_PROJECT, and optionally GOOGLE_CLOUD_LOCATION. Application Default Credentials must also be available inside the container, normally through a read-only credential mount. Do not bake API keys or service-account files into the image.

Running with Cline

1. Configure MCP Settings: Add/update the configuration in your Cline MCP settings file (e.g., .roo/mcp.json). You have two primary ways to configure the command:

   Option A: Using Node (Direct Path - Recommended for Development)

   This method uses node to run the compiled script directly. It's useful during development when you have the code cloned locally.

   config.json

   Copy

   {
     "mcpServers": {
       "google-ai-search-mcp": {
         "command": "node",
         "args": [
           "/full/path/to/your/google-ai-search-mcp/build/index.js" // Use absolute path or ensure it's relative to where Cline runs node
         ],
         "env": {
           // --- General AI Configuration ---
           "AI_PROVIDER": "vertex", // "vertex" or "gemini"
           // --- Required (Conditional) ---
           "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex"
           // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini"
           // --- Optional Model Selection ---
           "VERTEX_MODEL_ID": "gemini-2.5-pro", // If AI_PROVIDER="vertex" (Example override)
           "GEMINI_MODEL_ID": "gemini-2.5-pro", // If AI_PROVIDER="gemini"
           // --- Optional AI Parameters ---
           "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI
           "AI_TEMPERATURE": "0.0",
           "AI_USE_STREAMING": "true",
           "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example
           "AI_MAX_RETRIES": "3",
           "AI_RETRY_DELAY_MS": "1000",
           // --- Optional Vertex Authentication ---
           // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex
         },
         "disabled": false,
         "alwaysAllow": [
            // Add tool names here if you don't want confirmation prompts
            // e.g., "answer_query_websearch"
         ],
         "timeout": 3600 // Optional: Timeout in seconds
       }
       // Add other servers here...
     }
   }
   

   • Important: Ensure the args path points correctly to the build/index.js file. Using an absolute path might be more reliable.

   Option B: Using NPX (Requires Package Published to npm)

   This method uses npx to automatically download and run the server package from the npm registry. This is convenient if you don't want to clone the repository.

   config.json

   Copy

   {
     "mcpServers": {
       "google-ai-search-mcp": {
         "command": "bunx", // Use bunx
         "args": [
           "-y", // Auto-confirm installation
           "google-ai-search-mcp" // The npm package name
         ],
         "env": {
           // --- General AI Configuration ---
           "AI_PROVIDER": "vertex", // "vertex" or "gemini"
           // --- Required (Conditional) ---
           "GOOGLE_CLOUD_PROJECT": "YOUR_GCP_PROJECT_ID", // Required if AI_PROVIDER="vertex"
           // "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY", // Required if AI_PROVIDER="gemini"
           // --- Optional Model Selection ---
           "VERTEX_MODEL_ID": "gemini-2.5-pro", // If AI_PROVIDER="vertex" (Example override)
           "GEMINI_MODEL_ID": "gemini-2.5-pro", // If AI_PROVIDER="gemini"
           // --- Optional AI Parameters ---
           "GOOGLE_CLOUD_LOCATION": "us-central1", // Specific to Vertex AI
           "AI_TEMPERATURE": "0.0",
           "AI_USE_STREAMING": "true",
           "AI_MAX_OUTPUT_TOKENS": "65536", // Default from .env.example
           "AI_MAX_RETRIES": "3",
           "AI_RETRY_DELAY_MS": "1000",
           // --- Optional Vertex Authentication ---
           // "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json" // If using Service Account Key for Vertex
         },
         "disabled": false,
         "alwaysAllow": [
            // Add tool names here if you don't want confirmation prompts
            // e.g., "answer_query_websearch"
         ],
         "timeout": 3600 // Optional: Timeout in seconds
       }
       // Add other servers here...
     }
   }
   

   • Ensure the environment variables in the env block are correctly set, either matching .env or explicitly defined here. Remove comments from the actual JSON file.

2. Restart/Reload Cline: Cline should detect the configuration change and start the server.

3. Use Tools: You can now use the comprehensive list of Google AI-powered search and documentation tools via Cline.

Development

• Watch Mode: bun run watch
• Build: bun run build
• Inspector: bun run inspector

License

This project is licensed under the MIT License - see the LICENSE file for details.