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

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

Variable	Required	Description
GEMINI_API_KEY	Yes	Your Google Gemini API key

Tools (23)

Chat & Generation (6)

Tool	Description
gemini_chat	Send a prompt with optional search grounding and URL context
gemini_chat_multi	Multi-turn conversation with message history
gemini_chat_with_tools	Chat with mode switching: search, code, or all
gemini_search_grounded	Search-grounded generation with source citations
gemini_structured_output	Generate JSON output matching a provided schema
gemini_url_context	Analyze one or more URLs using Gemini's URL context tool

Multimodal Analysis (6)

Tool	Description
gemini_analyze_image	Analyze an image file with Gemini Vision (JPG, PNG, GIF, WebP, BMP, SVG)
gemini_analyze_audio	Transcribe, summarize, or describe audio (MP3, WAV, OGG, FLAC, AAC, M4A, Opus)
gemini_analyze_video	Analyze a video file; auto-uploads large files via Files API (MP4, AVI, MOV, MKV, WebM)
gemini_analyze_pdf	Analyze a PDF document (up to 2GB via Files API)
gemini_analyze_youtube	Analyze a public YouTube video by URL (no download needed)
gemini_analyze_url	Analyze content from an HTTP/HTTPS URL or GCS URI (gs://)

Deep Research (2)

Tool	Description
gemini_deep_research	Start a deep research task; sends push notification on completion
gemini_check_research	Check status of a running deep research task by interaction ID

Files API (3)

Tool	Description
gemini_upload_file	Upload a file to Gemini (up to 2GB, retained 48 hours)
gemini_list_files	List all uploaded files with metadata
gemini_delete_file	Delete an uploaded file by name

Utilities (6)

Tool	Description
gemini_list_models	List available Gemini models with capabilities and token limits
gemini_count_tokens	Count tokens in text using a model's tokenizer
gemini_embed	Generate text embeddings (default: gemini-embedding-001, 3072 dimensions)
gemini_code_execute	Execute Python code via Gemini's built-in sandbox
gemini_summarize	Summarize text with configurable style (brief, detailed, bullet-points)
gemini_translate	Translate text to any language with optional model override

Model Selection

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

Model	Best For
gemini-3.1-pro-preview	Default. Best quality for most tasks
gemini-2.5-flash	Faster responses, lower cost
gemini-embedding-001	Text embeddings (used by gemini_embed)
deep-research-pro-preview-12-2025	Deep research agent (used internally)

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

Package	Version	Purpose
@modelcontextprotocol/sdk	^1.0.0	MCP server framework
@google/genai	^1.0.0	Google Gemini AI SDK
zod	^3.24.0	Input schema validation

License

MIT