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:

bun install

3. Configure Environment:

4. Build the Server:

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.

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

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.

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

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.