MCP Gemini Grounding

🚀 Gemini AI MCP Server

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

🚀 Quick Start

Once you've completed the installation and configuration steps, the google_search tool will be available in Claude Code. You can use it by asking Claude to search and summarize information, such as "Search for the latest news about AI".

✨ Features

• Utilizes Gemini AI to conduct web searches and offer synthesized answers.
• Returns AI - generated summaries with proper citations and source URLs.
• Supports both OAuth and API key authentication.
• Is compatible with Claude Code and other MCP clients.

📦 Installation

Build from source

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

To view the 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

📚 Documentation

Prerequisites

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

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

3. Commit this file to version control.
4. 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 Examples

Basic Usage

Once configured, you can use the google_search tool in Claude Code 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?"

Advanced Usage

The tool provides synthesized answers with citations and source URLs, which can be used in more complex research scenarios. For example, when conducting in - depth research on a specific topic, you can use it to quickly obtain comprehensive and well - cited information.

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)

🔧 Technical Details

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

Demo