MCP Gemini Grounded Search

MCP Gemini Grounded Search is a Go-based MCP server that provides grounded search functionality using Google's Gemini API. MCP clients such as Claude Desktop and Claude Code can perform real-time web searches and retrieve up-to-date information with source attribution.

Features

• MCP Compliance: JSON-RPC based interface for tool execution per the MCP specification
• Grounded Search: Gemini API generates answers with source attributions
• Two Transport Modes: stdio (for Claude Desktop / Claude Code) and Streamable HTTP
• Flexible Configuration: config file, environment variables, or command-line flags

Requirements

• Docker (recommended)

For local development:

• Go 1.24 or later
• Gemini API key

Using with Docker (Recommended)

docker pull cnosuke/mcp-gemini-grounded-search:latest

docker run -i --rm -e GEMINI_API_KEY="your-api-key" cnosuke/mcp-gemini-grounded-search:latest server

Using with Claude Desktop (Docker)

Add an entry to your claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GEMINI_API_KEY=your-api-key", "cnosuke/mcp-gemini-grounded-search:latest", "server"]
    }
  }
}

Using with Claude Code (Docker)

claude mcp add-json mcp-gemini-grounded-search '{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "GEMINI_API_KEY",
    "-e", "GEMINI_MODEL_NAME",
    "-e", "GEMINI_THINKING_LEVEL",
    "cnosuke/mcp-gemini-grounded-search:latest",
    "server"
  ],
  "env": {
    "GEMINI_MODEL_NAME": "gemini-3.1-pro-preview",
    "GEMINI_THINKING_LEVEL": "LOW",
    "GEMINI_API_KEY": "<your-gemini-api-key>"
  }
}'

Building and Running (Go Binary)

# Build
make bin/mcp-gemini-grounded-search

# stdio mode (for Claude Desktop / Claude Code)
./bin/mcp-gemini-grounded-search server --config config.yml

# Streamable HTTP mode
./bin/mcp-gemini-grounded-search httpserver --config config.yml

Using with Claude Desktop (Go Binary)

{
  "mcpServers": {
    "gemini-search": {
      "command": "/path/to/mcp-gemini-grounded-search",
      "args": ["server", "--config", "/path/to/config.yml"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Streamable HTTP Mode

The httpserver subcommand starts an HTTP server compatible with the MCP Streamable HTTP transport.

HTTP_AUTH_TOKEN=secret GEMINI_API_KEY=your-key \
  ./bin/mcp-gemini-grounded-search httpserver --config config.yml

# Health check (no auth required)
curl http://localhost:8080/health

# MCP endpoint (auth required)
curl -H "Authorization: Bearer secret" http://localhost:8080/mcp

HTTP-specific settings can be configured entirely via environment variables — no need to put secrets in config.yml.

Configuration

config.yml

log: 'path/to/mcp-gemini-grounded-search.log'  # empty = no log output
debug: false

gemini:
  api_key: ''                      # Set via GEMINI_API_KEY env var
  model_name: 'gemini-3.1-pro-preview'
  max_tokens: 5000
  thinking_level: 'LOW'            # Gemini 3.x series: MINIMAL, LOW, MEDIUM, HIGH
  # thinking_budget: 0             # Gemini 2.5 series: token count (0 = disable thinking)

http:
  port: 8080
  endpoint_path: /mcp
  auth_token: ''                   # Set via HTTP_AUTH_TOKEN env var
  allowed_origins: []              # e.g. ['https://example.com'] — empty = allow all
  heartbeat_seconds: 30

Environment Variables

Configuration priority: defaults → config.yml → environment variables

Command-Line Options

server subcommand (stdio)

./bin/mcp-gemini-grounded-search server [options]

httpserver subcommand (Streamable HTTP)

./bin/mcp-gemini-grounded-search httpserver [options]

All HTTP settings (port, auth_token, etc.) are configured via environment variables or config.yml.

MCP Tools

search

Performs a web search using the Gemini API and returns a grounded answer with sources.

Parameters:

Response:

{
  "text": "Generated answer text",
  "groundings": [
    {
      "title": "Source title",
      "domain": "example.com",
      "url": "https://example.com/article"
    }
  ]
}

Logging

• Set log in config.yml or LOG_PATH env var to write logs to a file
• If log is empty, no log file is produced
• Set debug: true or DEBUG=true for verbose logging

Contributing

Contributions are welcome. Please fork the repository and submit pull requests for improvements or bug fixes. For major changes, open an issue first to discuss your ideas.

License

This project is licensed under the MIT License.

Author: cnosuke ( x.com/cnosuke )