Gemini MCP Server

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