Gemini CLI MCP Server

An MCP (Model Context Protocol) server that provides Google Search grounding capabilities using Gemini Code Assist. This server enables LLMs like Claude to perform web searches with citations and source attribution.

Features

• Google Search Grounding: Get answers with real-time web search results
• Source Citations: Responses include source URLs and citation mapping
• Automatic Token Refresh: OAuth credentials are automatically refreshed when expired
• Docker Support: Run as a containerized service with stdio or HTTP/SSE transport
• Multiple Models: Support for various Gemini models

Prerequisites

• Python 3.11+
• A Google account with access to Gemini Code Assist
• A Google OAuth client (set GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET) it is out there somewhere , search for it

Installation

Local Installation

1. Clone or download this directory
2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

Docker Installation

Build the Docker image:

docker build -t gemini-mcp .

Authentication Setup

Before using any scripts, you need to authenticate with Google.

Local Authentication

# Option A: export env vars
export GOOGLE_OAUTH_CLIENT_ID="...apps.googleusercontent.com"
export GOOGLE_OAUTH_CLIENT_SECRET="..."
python manual_auth.py

Docker Authentication

docker run -it --rm -e GOOGLE_OAUTH_CLIENT_ID="..." -e GOOGLE_OAUTH_CLIENT_SECRET="..." -p 8080:8080 -v ./config:/app/config gemini-mcp

On first run (when no credentials exist), the container will:

1. Display a URL to open in your browser for Google OAuth login
2. Guide you to paste the redirect URL back
3. Save your credentials to the config directory
4. Print your credential/project info
5. Start the MCP server in HTTP/SSE mode on port 8080

Important: Keep your credentials secure and never commit them to version control.

Docker Usage (HTTP/SSE)

The Docker container always starts the MCP server in HTTP/SSE mode.

Examples

# First run (interactive OAuth + start server)
docker run -it --rm -p 8080:8080 -v ./config:/app/config gemini-mcp

# Subsequent runs (no -it needed once credentials exist)
docker run -d -p 8080:8080 -v ./config:/app/config gemini-mcp

Available Scripts

server.py - MCP Server

The main MCP server that exposes the google_search tool.

# Run directly (defaults to HTTP/SSE on :8080)
python server.py

# If you need stdio transport (some MCP clients), set:
MCP_TRANSPORT=stdio python server.py

The server provides the following tool:

• google_search(query, model): Search using Gemini with Google Search grounding
  • query: The search query or question
  • model: The model to use (default: gemini-2.5-flash)

search.py - CLI Search

A command-line interface for quick searches without running the full MCP server.

# Basic search
python search.py "What is the latest news about AI?"

# Specify a model
python search.py "Explain quantum computing" --model gemini-2.5-pro

# Get help
python search.py --help

info.py - Credential Info

Display information about your current credentials and authentication status.

python info.py

This shows:

• User email and name
• Current tier and managed project
• Available tiers

manual_auth.py - Authentication

Perform OAuth authentication and save credentials.

python manual_auth.py

Available Models

The following Gemini models are supported:

Model	Description
gemini-2.5-flash	Fast, efficient model (default)
gemini-2.5-pro	More capable model for complex tasks
gemini-2.0-flash	Previous generation flash model
gemini-1.5-flash	Legacy flash model
gemini-1.5-pro	Legacy pro model

MCP Client Configuration

For clients that support HTTP/SSE transport, run the server in HTTP mode:

docker run -d -p 8080:8080 -v ./config:/app/config gemini-mcp

Then configure your MCP client:

{
  "mcpServers": {
    "gemini-search": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Environment Variables

Variable	Description	Default
CREDENTIALS_PATH	Directory containing credentials.json	. (local) or /app/config (Docker)
HOST	HTTP bind address	0.0.0.0
HTTP_PORT	HTTP port (preferred)	8080
PORT	HTTP port (legacy alias)	8080
MCP_TRANSPORT	MCP transport (sse or stdio)	sse

Setting Environment Variables

Local:

export CREDENTIALS_PATH=/path/to/dir
python server.py

Manual Google Cloud Setup

If automatic provisioning fails, you may need to set up the project manually:

1. Go to the Google Cloud Console.
2. Create or select a project.
3. Enable the Gemini for Google Cloud API (cloudaicompanion.googleapis.com).
4. Configure the projectId in your Opencode config as shown above.

Gemini Admin Settings

In Google Cloud Console, search for Admin for Gemini. Open it, go to Settings, then enable Preview on release channels for Gemini Code Assist in local IDEs.