Gemini AI MCP Server

A Model Context Protocol (MCP) server that provides AI-powered web search and summarization using the Gemini API's grounding feature. Unlike traditional search tools that return raw results, this server uses Gemini AI to synthesize information and provide comprehensive answers with citations.

Demo

Features

• Uses Gemini AI to search the web and provide synthesized answers
• Returns AI-generated summaries with proper citations and source URLs
• Supports both OAuth and API key authentication
• Compatible with Claude Code and other MCP clients

Prerequisites

• Go 1.21 or later
• Gemini API access (either API key or OAuth credentials)

Installation

Build from source

git clone https://github.com/ml0-1337/mcp-gemini-grounding.git
cd mcp-gemini-grounding
make build

For a full list of available commands, run:

make help

Install globally

# From source
make install

# Or using go install directly
go install github.com/ml0-1337/mcp-gemini-grounding/cmd/gemini-grounding@latest

Configuration

Authentication

The server supports two authentication methods:

1. OAuth Credentials (Preferred)

   • Automatically uses credentials from ~/.gemini/oauth_creds.json
   • These are created when you authenticate with the Gemini CLI
   • See OAuth2 Setup Guide for detailed instructions

2. API Key (Fallback)

   • Set the GEMINI_API_KEY environment variable
   • Get your API key from Google AI Studio

Claude Code Configuration

Choose the appropriate configuration scope based on your needs:

Important: When using the CLI commands below, you must provide the full absolute path to the binary (e.g., /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding). Relative paths like ./mcp-gemini-grounding will cause the server to fail.

1. Local Scope (Project-specific, Private)

Best for: Personal development servers, experimental configurations, or servers with sensitive credentials.

Option A: Using CLI (Recommended)

# If installed globally
claude mcp add gemini-grounding

# Or with full absolute path (required - relative paths will fail)
claude mcp add gemini-grounding /full/path/to/mcp-gemini-grounding
# Example: claude mcp add gemini-grounding /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding

Option B: Manual configuration

1. Open your project in Claude Code
2. Click on the MCP servers icon in the bottom status bar
3. Select "Add MCP Server..."
4. Choose "gemini" and configure:

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "/path/to/mcp-gemini-grounding",
      "env": {
        "GEMINI_API_KEY": "$GEMINI_API_KEY"
      }
    }
  }
}

This configuration is stored in your project's .claude/settings.local.json file and is not shared with others.

2. Project Scope (Team-shared)

Best for: Team collaboration where all members need the same MCP server configuration.

Option A: Using CLI (Recommended)

# If installed globally
claude mcp add gemini-grounding -s project

# Or with full absolute path (required - relative paths will fail)
claude mcp add gemini-grounding -s project /full/path/to/mcp-gemini
# Example: claude mcp add gemini-grounding -s project /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding

Option B: Manual configuration

1. Create a .mcp.json file in your project root
2. Add the following configuration:

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "mcp-gemini-grounding",
      "env": {
        "GEMINI_API_KEY": "$GEMINI_API_KEY"
      }
    }
  }
}

1. Commit this file to version control
2. Team members can set their GEMINI_API_KEY environment variable locally

Note: Never commit actual API keys. Always use environment variable references (e.g., $GEMINI_API_KEY).

3. User Scope (Global)

Best for: Personal utility servers you want available across all your projects.

Option A: Using CLI (Recommended)

# If installed globally
claude mcp add gemini-grounding -s user

# Or with full absolute path (required - relative paths will fail)
claude mcp add gemini-grounding -s user /full/path/to/mcp-gemini
# Example: claude mcp add gemini-grounding -s user /Users/username/projects/mcp-gemini-grounding/mcp-gemini-grounding

Option B: Manual configuration

1. Open Claude Code settings
2. Navigate to MCP Servers configuration
3. Add the gemini server to your user settings:

{
  "mcpServers": {
    "gemini-grounding": {
      "command": "gemini",
      "env": {
        "GEMINI_API_KEY": "$GEMINI_API_KEY"
      }
    }
  }
}

If you installed globally with go install, you can simply use "command": "gemini".

Setting Environment Variables

After adding the server, set your API key:

# macOS/Linux
export GEMINI_API_KEY="your-api-key-here"

# Windows (PowerShell)
$env:GEMINI_API_KEY="your-api-key-here"

# Windows (Command Prompt)
set GEMINI_API_KEY=your-api-key-here

For permanent configuration, add the export to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Configuration Precedence

Claude Code applies configurations in this order (highest to lowest priority):

1. Local scope - Project-specific settings override everything
2. Project scope - Shared team settings
3. User scope - Global personal settings

This allows personal configurations to override shared ones when needed.

Security Best Practices

1. API Key Management:

   • Never commit API keys directly in configuration files
   • Use environment variables: $GEMINI_API_KEY
   • Set the environment variable in your shell profile:

     export GEMINI_API_KEY="your-api-key-here"

2. OAuth Credentials:

   • The server automatically uses OAuth from ~/.gemini/oauth_creds.json if available
   • No configuration needed for OAuth - it's detected automatically

3. Team Environments:

   • Use project scope (.mcp.json) without sensitive data
   • Each team member sets their own API key locally
   • Consider using OAuth for better security

Usage

Once configured, the google_search tool will be available in Claude Code. You can use it by asking Claude to search and summarize information:

• "Search for the latest news about AI"
• "Find information about quantum computing"
• "What are the current trends in web development?"

Tool Schema

{
  "name": "google_search",
  "description": "Uses Google Search via Gemini AI grounding to find information and provide synthesized answers with citations. Returns AI-generated summaries rather than raw search results.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "The search query to find information on the web"
      }
    },
    "required": ["query"]
  }
}

Output Format

The tool returns search results with:

• Main content with inline citations (e.g., [1], [2])
• List of sources with titles and URLs
• Proper formatting for easy reading

Example output:

Web search results for "quantum computing":

Quantum computing is a rapidly evolving field[1]. Recent breakthroughs have shown promise for practical applications[2].

Sources:
[1] Quantum Computing Explained - MIT (https://mit.edu/quantum)
[2] Latest Quantum Breakthroughs - Nature (https://nature.com/quantum)

Development

Quick Start

# Install dependencies
make deps

# Build the project
make build

# Run tests
make test

# Run all quality checks
make audit

Available Make Commands

Run make help to see all available commands. Key commands include:

• Build & Run: make build, make run, make install
• Testing: make test, make cover, make test-race
• Quality: make fmt, make vet, make lint, make audit
• Development: make dev, make watch (requires air)
• Cross-platform: make build-all (builds for Linux, macOS, Windows)
• MCP Integration: make mcp-install, make mcp-config
• Release: make release, make checksum

Running tests

# Run all tests
make test

# Run tests with coverage
make cover

# Run tests with race detection
make test-race

# Generate HTML coverage report
make cover-html

Test Scripts

Various test scripts for OAuth2 and API testing are available in the scripts/test/ directory. See scripts/test/README.md for details.

Architecture

graph TD
    subgraph User
        A[MCP Client e.g. Claude Code]
    end

    subgraph "mcp-gemini-grounding"
        B[cmd/gemini-grounding/main.go]
        C[internal/search]
        D[internal/gemini]
        E[internal/auth]
    end

    subgraph "Google Cloud"
        F[Gemini API]
    end

    A -- MCP Request --> B
    B -- Initializes --> C
    B -- Initializes --> D
    B -- Initializes --> E
    C -- Uses --> D
    D -- Uses --> E
    D -- Makes API Calls --> F

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style F fill:#bbf,stroke:#333,stroke-width:2px

Project structure

mcp-gemini-grounding/
├── cmd/gemini-grounding/ # Main application entry point
├── internal/
│   ├── auth/           # Authentication handling
│   ├── gemini/         # Gemini API client
│   └── search/         # MCP tool handler
├── go.mod
├── go.sum
└── README.md

Troubleshooting

Authentication errors

1. Check OAuth credentials exist:

   ls ~/.gemini/oauth_creds.json

2. Or ensure API key is set:

   echo $GEMINI_API_KEY

Connection issues

• Ensure you have internet connectivity
• Check if Gemini API is accessible in your region
• Verify your API key or OAuth credentials are valid

No results

• Try different search queries
• Check the Gemini API status
• Ensure you have not exceeded rate limits

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.

Repository

https://github.com/ml0-1337/mcp-gemini-grounding