Gemini MCP Server

A Model Context Protocol (MCP) server providing 23 tools for Google's Gemini API -- chat, multimodal analysis, deep research, file management, YouTube analysis, and more.

Built with @google/genai SDK (v1.0.0+).

Features

• Chat with Gemini models (single-turn, multi-turn, with tool modes)

• Analyze images, audio, video, PDFs, YouTube videos, and URLs

• Files API with auto-switching: inline for small files (<20MB), upload for large (up to 2GB)

• Deep research agent with background polling and push notifications (Termux)

• Structured JSON output, embeddings, code execution, translation, summarization

• Google Search grounding and URL context

• Thinking mode enabled by default (budget: 65535 tokens)

• High media resolution by default

Related MCP server: Gemini Chat MCP

Prerequisites

• Node.js 18+

• A Gemini API key

Quick Install

git clone https://github.com/salviz/gemini-mcp-server.git
cd gemini-mcp-server
npm install

Register with Claude Code

CLI:

claude mcp add gemini -- node /path/to/gemini-mcp-server/index.js

Or add to your MCP config (~/.claude/claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "gemini": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/gemini-mcp-server/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables

Tools (23)

Chat & Generation (6)

Multimodal Analysis (6)

Deep Research (2)

Files API (3)

Utilities (6)

Model Selection

Default model: gemini-3.1-pro-preview. Every tool accepts an optional model parameter.

Files API & Large File Handling

The server automatically handles file size:

• <= 20MB: Sent inline as base64 (fast, no upload step)

• > 20MB up to 2GB: Uploaded via Gemini Files API, then referenced by URI

• YouTube URLs: Passed directly via fileData.fileUri (no download)

• HTTP/HTTPS URLs: Passed via createPartFromUri (up to 100MB)

• GCS URIs (gs://): Passed via fileData.fileUri

Uploaded files are retained for 48 hours. Use gemini_list_files and gemini_delete_file to manage them.

Deep Research

The gemini_deep_research tool uses Gemini's Interactions API with the deep-research-pro-preview-12-2025 agent:

1. Starts research in background mode

2. Polls for 50 seconds in case it finishes quickly

3. If still running, starts background polling (every 30s, up to 30 minutes)

4. Sends a push notification via termux-notification when complete

5. Saves full results to ~/.cache/deep_research_*.txt

Use gemini_check_research to manually poll at any time.

Project Structure

gemini-mcp-server/
  index.js              # Server entry point
  tools/
    shared.js           # Shared config, AI client, extractText helper
    chat.js             # 17 tools: chat, analysis, research, files, YouTube
    utility.js          # 6 tools: models, tokens, embed, code, summarize, translate
  package.json

Security

• API key from environment only -- never hardcoded in source

• File paths validated -- absolute paths required, existence checked before reading

• Stdio transport -- no network server exposed

• No data logged or stored -- prompts and responses are not persisted

Dependencies

License

MIT