Skip to main content
Glama
mnthe

gemini-mcp-server

by mnthe
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

gemini-mcp-server

An intelligent MCP (Model Context Protocol) server that enables AI assistants to query Google AI (Gemini models) via Vertex AI or Google AI Studio with agentic capabilities - automatic tool selection, multi-turn reasoning, MCP-to-MCP delegation, and multimodal input support.

Purpose

This server provides:

  • Agentic Loop: Turn-based execution with automatic tool selection and reasoning

  • Query Gemini: Access Gemini models via Vertex AI or Google AI Studio

  • Multimodal Support: Send images, audio, video, and code files alongside text prompts

  • Image Generation: Generate images using Gemini image models (gemini-3-pro-image, gemini-3.1-flash-image, gemini-3.1-flash-lite-image, gemini-2.5-flash-image)

  • Speech & Music Generation: Generate TTS audio with Gemini TTS and music with Lyria

  • Tool Execution: Built-in WebFetch + integration with external MCP servers

  • Multi-turn Conversations: Maintain context across queries with session management

  • Reasoning Traces: File-based logging of AI thinking processes

  • Gemini 3 Support: Full support for Gemini 3 models including thinkingLevel parameter

Related MCP server: Gemini Chat MCP

Key Features

🎭 System Prompt Customization

Customize the AI assistant's behavior and persona:

  • Domain-Specific Roles: Configure as financial analyst, code reviewer, research assistant, etc.

  • Environment-Based: Set via GEMINI_SYSTEM_PROMPT environment variable

  • Multi-Persona Support: Run multiple servers with different personas

  • 100% Backward Compatible: Optional feature - works normally without customization

  • See PROMPT_CUSTOMIZATION.md for detailed guide and examples/custom-prompts.md for templates

🎨 Multimodal Input Support

Send images, audio, video, and code files to Gemini:

  • Images: JPEG, PNG, WebP, HEIC, HEIF

  • Videos: MP4, MOV, AVI, WebM, and more

  • Audio: MP3, WAV, AAC, FLAC, and more

  • Documents/Code: PDF, text files, code files (Python, JavaScript, etc.)

  • Support for both base64-encoded inline data and Cloud Storage URIs

  • See MULTIMODAL.md for detailed documentation

🤖 Intelligent Agentic Loop

Inspired by OpenAI Agents SDK, the server operates as an autonomous agent:

  • Turn-based execution (up to 10 turns per query)

  • Automatic tool selection based on LLM decisions

  • Parallel tool execution with retry logic

  • Smart fallback to Gemini knowledge when tools fail

🔮 Gemini 3 Model Support

Full support for Gemini 3 generation models:

  • gemini-3.6-flash: Default model — efficient agentic and multimodal workhorse

  • gemini-3.1-pro-preview: High-capability reasoning model

  • gemini-3.5-flash-lite: Fast, cost-efficient multimodal model for high-volume workloads

  • gemini-3.1-pro-preview-customtools: Agentic endpoint optimized for custom tools

  • thinkingLevel: Per-query thinking budget control for Gemini 3 models

  • GEMINI_MEDIA_RESOLUTION: Control media quality for multimodal inputs

🛠️ Built-in Tools

  • WebFetch: Secure HTTPS-only web content fetching with private IP blocking

  • MCP Integration: Dynamic discovery and execution of external MCP server tools

🖼️ Image Generation

Generate images directly from text prompts using Gemini image models:

  • gemini-3-pro-image: Professional asset production with 4K resolution support (default)

  • gemini-3.1-flash-image: High-efficiency generation with 0.5K-4K resolution and reference images

  • gemini-3.1-flash-lite-image (Nano Banana 2 Lite): Fast, low-cost GA tier — 1K output only, standard aspect ratios, up to 14 reference images, image editing (recommended replacement for gemini-2.5-flash-image)

  • gemini-2.5-flash-image: Fast 1K image generation and editing (legacy, retiring 2026-10-02; prefer gemini-3.1-flash-lite-image)

  • Configurable aspect ratios: 1:1, 16:9, 9:16, 4:3, and more

  • Images automatically saved to configurable output directory

🎧 Audio Generation

Generate file-based audio outputs:

  • generate_speech: Gemini TTS single-speaker or two-speaker speech, saved as WAV

  • generate_music: Lyria 3 music generation, saved as MP3; Gemini API/AI Studio mode can request WAV for lyria-3-pro-preview

  • Speech defaults to ~/Music/gemini-generated/speech; music defaults to ~/Music/gemini-generated/music

  • Generation failures return structured MCP error content with status, tool, errorType, message, and validation issues when available

  • See GENERATION.md, AUDIO_GENERATION.md, examples/audio-generation.md, and examples/video-generation.md

🔎 AI-Assisted Reference Search

  • reference_search: Answer a question from live web sources using Gemini's Google Search grounding, returning a synthesized answer plus organized citations (links) and claim→source supports in one call

  • Search-scope tuning is backend-specific: Vertex AI supports excludeDomains and blockingConfidence; Google AI Studio supports timeRange and grounding on explicit urls (URL context); both support includeImages

🔐 Security First

Multi-Layer Defense:

  • SSRF Protection: HTTPS-only URL fetching, private IP blocking (10.x, 172.16.x, 192.168.x, 127.x, 169.254.x), cloud metadata endpoint blocking (AWS, GCP, Azure)

  • Prompt Injection Guardrails: External content tagging, trust boundaries, system prompt hardening

  • File Security: MIME type validation, executable file rejection, path traversal prevention, directory whitelist

  • Redirect Validation: Manual redirect handling with security checks, maximum 5 redirects, cross-domain blocking

  • Content Boundaries: 50KB size limits, external content wrapping with security tags

Comprehensive Testing: 69 security-focused tests covering SSRF, path traversal, MIME validation, and prompt injection.

See SECURITY.md for detailed security documentation and best practices.

📝 Observability

  • File-based logging (logs/general.log, logs/reasoning.log)

  • Configurable log directory or disable logging for npx/containerized environments

  • Detailed execution traces for debugging

  • Turn and tool usage statistics

Prerequisites

  • Node.js 18 or higher

  • Google Cloud Platform account with Vertex AI enabled, or a Google AI Studio API key

  • Google Cloud credentials configured for Vertex AI mode

Quick Start

Installation

Option 1: npx (Recommended)

npx -y github:mnthe/gemini-mcp-server

Option 2: From Source

git clone https://github.com/mnthe/gemini-mcp-server.git
cd gemini-mcp-server
npm install
npm run build

Authentication

The server supports both Vertex AI and Google AI Studio / Gemini Developer API mode.

Vertex AI mode:

Application Default Credentials (Recommended):

gcloud auth application-default login

Or use Service Account:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

Google AI Studio mode:

export GEMINI_API_KEY="your-ai-studio-api-key"
export GOOGLE_GENAI_USE_VERTEXAI="false"

Configuration

Required Environment Variables:

# Vertex AI mode
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

# Or Google AI Studio mode
export GEMINI_API_KEY="your-ai-studio-api-key"
export GOOGLE_GENAI_USE_VERTEXAI="false"

Optional Model Settings:

export GEMINI_MODEL="gemini-3.6-flash"  # Default model
export GEMINI_TEMPERATURE="1.0"
export GEMINI_MAX_TOKENS="8192"
export GEMINI_TOP_P="0.95"
export GEMINI_TOP_K="40"

Sampling overrides are sent only to older models that support them. Gemini 3.6 Flash and Gemini 3.5 Flash-Lite use their model defaults.

Optional Agentic Features:

# System prompt customization
export GEMINI_SYSTEM_PROMPT="You are a specialized financial analyst AI assistant. You have access to the following tools:"

# Multi-turn conversations
export GEMINI_ENABLE_CONVERSATIONS="true"
export GEMINI_SESSION_TIMEOUT="3600"
export GEMINI_MAX_HISTORY="10"

# Logging configuration
# Default: Console logging to stderr (recommended for npx/MCP usage)
export GEMINI_LOG_TO_STDERR="true"         # Default: true (console logging)

# For file-based logging instead:
export GEMINI_LOG_TO_STDERR="false"        # Disable console, use file logging
export GEMINI_LOG_DIR="./logs"             # Log directory (default: ./logs)

# To disable logging completely:
export GEMINI_DISABLE_LOGGING="true"

# File URI support (for CLI environments only)
export GEMINI_ALLOW_FILE_URIS="true"       # Set to 'true' to allow file:// URIs (CLI tools only, NOT for desktop apps)

# Media resolution for Gemini 3 models (videoMetadata and image quality)
export GEMINI_MEDIA_RESOLUTION="medium"    # Options: low, medium, high (default: not set)

# Image generation output directory
export GEMINI_IMAGE_OUTPUT_DIR="/path/to/images"  # Default: ~/Pictures/gemini-generated
export GEMINI_VIDEO_OUTPUT_DIR="/path/to/videos"  # Default: ~/Movies/gemini-generated on macOS, ~/Videos/gemini-generated on Windows/Linux
export GEMINI_SPEECH_OUTPUT_DIR="/path/to/speech" # Default: ~/Music/gemini-generated/speech
export GEMINI_MUSIC_OUTPUT_DIR="/path/to/music"   # Default: ~/Music/gemini-generated/music

# External MCP servers (for tool delegation)
export GEMINI_MCP_SERVERS='[
  {
    "name": "filesystem",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
  },
  {
    "name": "web-search",
    "transport": "http",
    "url": "http://localhost:3000/mcp"
  }
]'

MCP Client Integration

Add to your MCP client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "github:mnthe/gemini-mcp-server"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id",
        "GOOGLE_CLOUD_LOCATION": "us-central1",
        "GEMINI_MODEL": "gemini-3.6-flash",
        "GEMINI_ENABLE_CONVERSATIONS": "true"
      }
    }
  }
}

Claude Code (.claude.json in project root):

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "github:mnthe/gemini-mcp-server"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id",
        "GOOGLE_CLOUD_LOCATION": "us-central1",
        "GEMINI_MODEL": "gemini-3.6-flash"
      }
    }
  }
}

Other MCP Clients (Generic stdio):

# Command to run
npx -y github:mnthe/gemini-mcp-server

# Or direct execution
node /path/to/gemini-mcp-server/build/index.js

Multi-Persona Setup

You can run multiple Gemini servers with different personas for specialized tasks:

{
  "mcpServers": {
    "gemini-code": {
      "command": "npx",
      "args": ["-y", "github:mnthe/gemini-mcp-server"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id",
        "GOOGLE_CLOUD_LOCATION": "us-central1",
        "GEMINI_SYSTEM_PROMPT": "You are a code review specialist. Focus on code quality, security, and best practices. You have access to the following tools:"
      }
    },
    "gemini-research": {
      "command": "npx",
      "args": ["-y", "github:mnthe/gemini-mcp-server"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id",
        "GOOGLE_CLOUD_LOCATION": "us-central1",
        "GEMINI_SYSTEM_PROMPT": "You are an academic research assistant. Cite sources and provide comprehensive analysis. You have access to the following tools:"
      }
    }
  }
}

See PROMPT_CUSTOMIZATION.md for comprehensive guide and examples/custom-prompts.md for ready-to-use templates.

Available Tools

The server exposes ten MCP tools: query, search, fetch, generate_image, generate_speech, generate_music, generate_video, check_video, generate_omni_video, and reference_search.

When both Vertex AI and Google AI Studio credentials are configured, query, generation tools, and reference_search also accept backend (vertex or ai-studio) to route a single request to a specific backend. In single-backend deployments, stray backend arguments are ignored.

query

Main agentic entrypoint that handles multi-turn execution with automatic tool selection and multimodal input support.

Parameters:

  • prompt (string, required): The text prompt to send

  • sessionId (string, optional): Conversation session ID

  • model (string, optional): Model override (e.g., gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3.1-pro-preview, gemini-3.1-pro-preview-customtools)

  • backend (string, optional): Request backend override, vertex or ai-studio (advertised when both backends are configured)

  • thinkingLevel (string, optional): Gemini 3 thinking level. Options: minimal, low, medium, high

  • mediaResolution (string, optional): Global media resolution for multimodal inputs. Options: low, medium, high

  • parts (array, optional): Multimodal content parts (images, audio, video, documents)

How It Works:

  1. Analyzes the prompt and conversation history (including multimodal content)

  2. Decides whether to use tools or respond directly

  3. Executes tools in parallel if needed (WebFetch, MCP tools)

  4. Retries failed tools with exponential backoff

  5. Falls back to Gemini knowledge if tools fail

  6. Continues for up to 10 turns until final answer

Examples:

# Simple text query
query: "What is the capital of France?"

# Complex query with tool usage
query: "Fetch the latest news from https://example.com/news and summarize"
→ Automatically uses WebFetch tool
→ Synthesizes content into answer

# Image analysis (multimodal)
query: "What's in this image?"
parts: [{ inlineData: { mimeType: "image/jpeg", data: "<base64>" } }]

# Multi-turn conversation
query: "What is machine learning?" (sessionId auto-created)
query: "Give me an example" (uses sessionId from previous response)

Multimodal Support: See MULTIMODAL.md for detailed documentation on:

  • Parts array structure and field requirements (for agent developers)

  • Supported file types (images, audio, video, documents)

  • Base64 inline data vs Cloud Storage URIs

  • Complete schema and validation rules

  • Usage examples and code samples

  • Best practices and limitations

  • Common mistakes to avoid

Response Includes:

  • Final answer

  • Session ID (if conversations enabled)

  • Statistics: turns used, tool calls, reasoning steps

search

Search for information using Gemini (OpenAI MCP spec).

Parameters:

  • query (string, required): Search query

Returns:

  • results: Array of {id, title, url}

fetch

Fetch full content of a search result (OpenAI MCP spec).

Parameters:

  • id (string, required): Document ID from search results

Returns:

  • id (string): Document identifier

  • title (string): Document title

  • text (string): Full document content

  • url (string): Document URL

  • metadata (object, optional): Search context from the original search result:

    • query (string): Original search query

    • timestamp (string): ISO 8601 timestamp when the search result was cached

    • model (string): Gemini model used for the search

generate_image

Generate images from text prompts using Gemini image models.

Parameters:

  • prompt (string, required): Image generation prompt describing what to generate

  • model (string, optional): Image model to use. Options:

    • gemini-3-pro-image (default) — professional quality, supports up to 4K resolution

    • gemini-3.1-flash-image — high-efficiency with 0.5K-4K and reference image support

    • gemini-3.1-flash-lite-image (Nano Banana 2 Lite) — fast, low-cost GA tier; 1K output only, standard aspect ratios (no 1:4/1:8/4:1/8:1), no thinkingLevel, up to 14 reference images and image editing (recommended replacement for gemini-2.5-flash-image)

    • gemini-2.5-flash-image — fast 1K image generation and editing (legacy, retiring 2026-10-02; prefer gemini-3.1-flash-lite-image)

  • backend (string, optional): Request backend override, vertex or ai-studio (advertised when both backends are configured)

  • aspectRatio (string, optional): Image aspect ratio. Default: 1:1. Options: 1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9 (1:4, 1:8, 4:1, 8:1 require gemini-3.1-flash-image)

  • imageSize (string, optional): Output resolution. Default: 1K. Options: 0.5K, 1K, 2K, 4K (0.5K requires gemini-3.1-flash-image; gemini-3.1-flash-lite-image supports 1K only; omit for gemini-2.5-flash-image)

  • imagePaths (array, optional): Local reference images for editing or style transfer (max 14; gemini-2.5-flash-image supports at most 3). Supported file types: PNG (.png), JPEG (.jpg, .jpeg), WEBP (.webp), HEIC (.heic), HEIF (.heif)

  • systemInstruction (string, optional): System instruction for Gemini 3 image models

  • thinkingLevel (string, optional): Gemini 3.1 Flash Image thinking level: minimal or high

  • mediaResolution (string, optional): Media resolution for reference image inputs: low, medium, high

Behavior:

  • Generated images are saved to GEMINI_IMAGE_OUTPUT_DIR (defaults to ~/Pictures/gemini-generated on macOS, Windows, and Linux)

  • Returns image data (base64) along with file paths of saved images

Examples:

# Generate a square image with default model
generate_image: "A serene mountain landscape at sunset"

# Generate a wide-format image with Nano Banana 2 at 4K
generate_image: "Futuristic cityscape at night"
model: "gemini-3.1-flash-image"
aspectRatio: "16:9"
imageSize: "4K"

generate_speech

Generate speech from text using Gemini TTS models.

Parameters:

  • prompt (string, required): Text or transcript to synthesize

  • model (string, optional): Speech model. gemini-3.1-flash-tts-preview (default) works on both backends. The 2.5 tiers differ per backend: Vertex AI uses gemini-2.5-flash-tts / gemini-2.5-pro-tts; Google AI Studio uses gemini-2.5-flash-preview-tts / gemini-2.5-pro-preview-tts

  • backend (string, optional): Request backend override, vertex or ai-studio (advertised when both backends are configured)

  • voiceName (string, optional): Prebuilt voice for single-speaker TTS. Default: Kore

  • languageCode (string, optional): BCP-47 language code

  • speakers (array, optional): Exactly two { speaker, voiceName } entries for multi-speaker TTS

Behavior:

  • Generated speech is saved to GEMINI_SPEECH_OUTPUT_DIR (defaults to ~/Music/gemini-generated/speech)

  • Returns MCP audio content and saved file paths

  • Gemini TTS is text-only input; audio, image, and video reference files are not supported by generate_speech

generate_music

Generate music using Lyria 3 models.

Parameters:

  • prompt (string, required): Music generation prompt

  • model (string, optional): Music model. Options: lyria-3-clip-preview (default), lyria-3-pro-preview

  • backend (string, optional): Request backend override, vertex or ai-studio (advertised when both backends are configured)

  • outputMimeType (string, optional): Vertex AI mode supports audio/mp3 only. Gemini API/AI Studio mode supports audio/mp3, or audio/wav with lyria-3-pro-preview

  • imagePaths (array, optional): Local image paths for multimodal music generation inputs (max 10). Supported file types: PNG (.png), JPEG (.jpg, .jpeg), WEBP (.webp), HEIC (.heic), HEIF (.heif)

  • lyrics (string, optional): User-provided lyrics

  • instrumental (boolean, optional): Request instrumental-only output; cannot be combined with lyrics or vocalStyle

  • vocalStyle (string, optional): Vocal generation direction

  • language (string, optional): Output language direction. Options: English, German, Spanish, French, Hindi, Japanese, Korean, Portuguese

  • durationSeconds (number, optional): Target duration in seconds; requires lyria-3-pro-preview; max 184 seconds

  • bpm (number, optional): Tempo direction in beats per minute

  • intensity (string, optional): low, medium, or high

Behavior:

  • Generated music is saved to GEMINI_MUSIC_OUTPUT_DIR (defaults to ~/Music/gemini-generated/music)

  • Returns MCP audio content, saved file paths, and any lyrics/song-structure text returned by Lyria

  • Lyria 3 Clip is fixed at 30 seconds; Lyria 3 Pro supports longer structured songs up to 184 seconds

  • Lyria 3 output is 44.1 kHz, one clip per prompt; Vertex AI mode supports 192 kbps MP3 only, while Gemini API/AI Studio Pro can also request WAV

  • Lyria 3 accepts text prompts and optional image references only; audio and video reference files are not supported by generate_music; negative prompting is not supported

generate_video

Generate videos from text prompts using Veo video generation models.

Parameters:

  • prompt (string, required): Video generation prompt describing what to generate

  • backend (string, optional): Request backend override, vertex or ai-studio (advertised when both backends are configured)

  • model (string, optional): Video model to use. Defaults to the fast model for the selected backend. Vertex AI options:

    • veo-3.1-fast-generate-001

    • veo-3.1-generate-001

    • veo-3.1-lite-generate-001 Google AI Studio options:

    • veo-3.1-fast-generate-preview

    • veo-3.1-generate-preview

    • veo-3.1-lite-generate-preview

  • aspectRatio (string, optional): Video aspect ratio. Default: 16:9. Options: 16:9, 9:16

  • durationSeconds (string, optional): Video duration. Default: 8. Options: 4, 6, 8 (1080p/4k require 8)

  • resolution (string, optional): Video resolution. Default: 720p. Options: 720p, 1080p, 4k (1080p/4k require 8 second duration)

  • generateAudio (boolean, optional): Generate audio for the video. Vertex AI only; Google AI Studio has audio always on

  • enhancePrompt (boolean, optional): Use Veo prompt rewriting/enhancement

  • personGeneration (string, optional): Person generation control: allow_all, allow_adult, dont_allow. Google AI Studio accepts allow_all for text/video extension and allow_adult for image/reference modes

  • negativePrompt (string, optional): Description of what to exclude from the video

  • seed (number, optional): Random seed for reproducibility. Vertex AI only

  • numberOfVideos (number, optional): Number of videos to generate. Default: 1; max 4 on Vertex AI, fixed to 1 on Google AI Studio

  • imagePath (string, optional): Local file path of input image for image-to-video generation. Supported file types: PNG (.png), JPEG (.jpg, .jpeg), WEBP (.webp)

  • lastFramePath (string, optional): Local file path of last frame for interpolation (requires imagePath). Same supported image file types as imagePath

  • referenceImagePaths (array, optional): Local file paths of reference images for style guidance (max 3, Veo 3.1 only). Same supported image file types as imagePath

  • videoPath (string, optional): Local file path of a Veo-generated 720p MP4 (.mp4) video to extend

  • compressionQuality (string, optional): Vertex AI output compression quality: optimized or lossless

  • resizeMode (string, optional): Vertex AI image-to-video fit mode for imagePath: crop or pad

Behavior:

  • Generated videos are saved to GEMINI_VIDEO_OUTPUT_DIR (defaults to ~/Movies/gemini-generated on macOS, ~/Videos/gemini-generated on Windows/Linux)

  • generate_video returns an operation ID; check_video polls the operation and returns saved file paths when complete

  • Supports text-to-video, image-to-video, interpolation, reference image, and Veo video extension modes

  • Veo 3.1 Lite does not support 4k or reference asset images; Vertex AI uses -001 model ids and Google AI Studio uses -preview model ids

  • Audio file references are not supported by generate_video; describe dialogue, sound effects, and ambience in prompt

Examples:

# Simple text-to-video
generate_video: "A dancing robot in a cyberpunk city"

# Text-to-video with custom settings
generate_video: "Ocean waves crashing on a beach"
model: "veo-3.1-generate-001"
aspectRatio: "16:9"
durationSeconds: "8"
resolution: "1080p"

# Image-to-video (animation)
generate_video: "Animate this image"
imagePath: "/path/to/image.jpg"

# Interpolation (morph between two frames)
generate_video: "Smooth transition"
imagePath: "/path/to/start_frame.jpg"
lastFramePath: "/path/to/end_frame.jpg"

# Video with reference images for style
generate_video: "Generate a video with cyberpunk aesthetic"
referenceImagePaths: ["/path/to/style1.jpg", "/path/to/style2.jpg"]

# Extend a previous Veo-generated video
generate_video: "Follow the subject as the scene continues into the hallway"
videoPath: "/path/to/previous-veo-output.mp4"
resolution: "720p"

generate_omni_video

Generate or conversationally edit short videos with Gemini Omni Flash (gemini-omni-flash-preview). This is a non-Veo video model on the Google AI Studio (Gemini API) backend, using the Interactions API. Unlike generate_video/check_video, it is synchronous — a single call returns the finished, saved video (no operation ID, no polling).

Parameters:

  • prompt (string, required): Video prompt for a new generation (oneshot), or a natural-language edit instruction when previousInteractionId is set

  • model (string, optional): Omni video model. Options: gemini-omni-flash-preview (default)

  • backend (string, optional): Request backend override. Omni Flash defaults to Google AI Studio (ai-studio); Vertex AI availability is rolling out

  • aspectRatio (string, optional): Aspect ratio. Default: 16:9. Options: 16:9, 9:16. Output is 720p only; clips run a few seconds — steer timing within the prompt (Omni Flash has no structured duration parameter)

  • imagePaths (array, optional): Local file paths of source/reference images for image-to-video or reference-to-video (max 7). Supported file types: PNG (.png), JPEG (.jpg, .jpeg), WEBP (.webp). Omit for interactive edits

  • previousInteractionId (string, optional): Interaction ID from a prior generate_omni_video call. When set, conversationally edits that video (no image re-upload) instead of generating a new one

Behavior:

  • Two paths: (1) oneshot generation — text-to-video, or image/reference-to-video via imagePaths; (2) interactive editing — set previousInteractionId to edit a prior video with a natural-language instruction (no image re-upload; chain up to 3 sequential edits)

  • 720p output only; a synced audio track is generated automatically (audio reference inputs are not accepted — describe dialogue, sound effects, and ambience in prompt)

  • Generated videos are saved to GEMINI_VIDEO_OUTPUT_DIR (defaults to ~/Movies/gemini-generated on macOS, ~/Videos/gemini-generated on Windows/Linux)

  • The response includes interactionId (pass it back as previousInteractionId to edit) and the saved video file path

Examples:

# Oneshot text-to-video
generate_omni_video: "A golden retriever surfing a wave at sunset"
aspectRatio: "16:9"

# Image-to-video
generate_omni_video: "Animate this scene with gentle camera motion"
imagePaths: ["/path/to/frame.png"]

# Interactive edit of a prior result
generate_omni_video: "Make it night time and add rain"
previousInteractionId: "<interactionId from previous call>"

reference_search

AI-assisted reference search: answer a question from live web sources using Gemini's Google Search grounding, and return organized citations. Unlike the OpenAI-spec search/fetch connector tools, this composes a synthesized answer and returns the source links plus claim→source supports in one call.

Parameters:

  • prompt (string, required): Research question or topic to answer from live web sources

  • backend (string, optional): Request backend override, vertex or ai-studio (advertised when both backends are configured)

  • model (string, optional): Gemini model override; must support Google Search grounding (default: server model)

  • excludeDomains (array, optional): Domains to exclude from results, e.g. ["reddit.com","pinterest.com"] (max 2000). Vertex AI backend only

  • blockingConfidence (string, optional): Block risky/low-quality sites at or above this confidence. Options: low (most aggressive), medium, high. Vertex AI backend only

  • timeRange (object, optional): Restrict results to a publish-time window (startTime/endTime, both required RFC 3339). Google AI Studio backend only

  • includeImages (boolean, optional): Also enable image-search grounding in addition to web search

  • urls (array, optional): Specific http(s) URLs to ground the answer on via URL context (max 20). Google AI Studio backend only — the URL context tool is not available on Vertex AI

  • systemInstruction (string, optional): System instruction to steer the tone, depth, or scope of the answer

  • thinkingLevel (string, optional): Gemini 3 thinking level override. Options: minimal, low, medium, high

Behavior:

  • Returns a JSON payload: answer (synthesized text), citations (deduped {index,title,uri,domain} sources), supports (answer segments mapped to citation indices with confidence scores), searchQueries (the queries the model actually ran), and searchSuggestionsHtml (Google's required Search Suggestions markup to display alongside the answer)

  • Search-scope tuning is backend-asymmetric — invalid combinations are rejected at validation with a structured error naming the supported backend

  • When urls are supplied, a URL context tool is added so the model also grounds on those specific pages

Examples:

# Recency-tuned research on Google AI Studio
reference_search: "What changed in the latest Gemini API pricing?"
backend: "ai-studio"
timeRange: { "startTime": "2026-06-01T00:00:00Z", "endTime": "2026-07-01T00:00:00Z" }

# Curated web research on Vertex AI (skip low-signal domains)
reference_search: "Production best practices for MCP servers"
excludeDomains: ["reddit.com", "pinterest.com"]
blockingConfidence: "medium"

# Ground on specific pages
reference_search: "Summarize the key points from these docs"
urls: ["https://ai.google.dev/gemini-api/docs/grounding"]

Security

The gemini-mcp-server implements comprehensive security measures to protect against common vulnerabilities. See SECURITY.md for complete documentation.

Defense Layers

1. SSRF (Server-Side Request Forgery) Protection

  • HTTPS-only: HTTP requests are blocked; only HTTPS is allowed for web resources

  • Private IP blocking: Blocks access to internal networks (10.x, 172.16.x, 192.168.x, 127.x, 169.254.x)

  • Cloud metadata blocking: Prevents access to AWS, GCP, Azure, and Alibaba Cloud metadata endpoints

  • Redirect validation: All redirects are manually validated; cross-domain redirects are blocked

2. Prompt Injection Guardrails

  • Trust boundaries: Clear separation between user input (trusted) and external content (untrusted)

  • Content tagging: All fetched web content is wrapped in <external_content> tags with security warnings

  • System prompt hardening: Built-in instructions to ignore malicious commands in external content

  • Information disclosure protection: Guidelines prevent revealing system prompts or internal details

3. File Security (Multimodal Content)

  • MIME type validation: Only known safe types (images, video, audio, PDF, code) are allowed

  • Executable rejection: Blocks .exe, .sh, .dll, and other executable file types

  • Path traversal prevention: All paths are normalized and validated against a whitelist

  • Directory whitelist: Local files only allowed in safe directories (cwd, Documents, Downloads, Desktop)

  • URI scheme validation: Only gs://, https://, and conditionally file:// URIs are allowed

4. Content Boundaries

  • Size limits: Web content limited to 50KB to prevent resource exhaustion

  • Content type validation: Basic validation of response content types

  • Encoding validation: Proper handling of character encodings

Configuration

File Security (Multimodal)

# Default: false (secure) - file:// URIs are disabled
export GEMINI_ALLOW_FILE_URIS="false"

# For CLI environments only - enables local file:// URIs with whitelist validation
export GEMINI_ALLOW_FILE_URIS="true"

Security Note: Never enable GEMINI_ALLOW_FILE_URIS in production or web-facing applications. It's designed for trusted CLI environments only.

Security Monitoring

# Enable logging to monitor security events
export GEMINI_DISABLE_LOGGING="false"
export GEMINI_LOG_DIR="/var/log/gemini-mcp"

# Log to stderr for real-time monitoring
export GEMINI_LOG_TO_STDERR="true"

Best Practices

For Desktop Applications (Recommended)

{
  "mcpServers": {
    "gemini": {
      "env": {
        "GEMINI_ALLOW_FILE_URIS": "false"
      }
    }
  }
}

For CLI Tools (Use with Caution)

export GEMINI_ALLOW_FILE_URIS="true"
export GEMINI_LOG_TO_STDERR="true"

Security Testing

Run comprehensive security test suite:

# All security tests
npx tsx test/url-security-test.ts        # 21 tests - SSRF protection
npx tsx test/file-security-test.ts       # 34 tests - File validation
npx tsx test/webfetch-security-test.ts   # 5 tests - Content tagging
npx tsx test/security-guidelines-test.ts # 3 tests - Prompt injection
npx tsx test/multimodal-security-test.ts # 6 tests - Multimodal files

Total: 69 security-focused tests covering SSRF, path traversal, MIME validation, and prompt injection.

For detailed security information, threat models, and vulnerability reporting, see SECURITY.md.

Architecture

Agentic Loop

User Query
  ↓
┌─── Turn 1..10 Loop ───┐
│                        │
│  1. Build Prompt       │
│     + Tool Definitions │
│     + History          │
│                        │
│  2. Gemini Generation  │
│     (with thinking)    │
│                        │
│  3. Parse Response     │
│     - Reasoning?       │
│     - Tool Calls?      │
│     - Final Output?    │
│                        │
│  4. Execute Tools      │
│     (parallel + retry) │
│                        │
│  5. Check MaxTurns     │
│     Continue or Exit?  │
│                        │
└────────────────────────┘
  ↓
Final Result + Stats

Project Structure

src/
├── agentic/           # Core agentic loop
│   ├── AgenticLoop.ts       # Main orchestrator
│   ├── RunState.ts          # Turn-based state management
│   ├── ResponseProcessor.ts # Parse Gemini responses
│   └── Tool.ts              # Tool interface (MCP standard)
│
├── mcp/               # MCP client implementation
│   ├── EnhancedMCPClient.ts # Unified stdio + HTTP client
│   ├── StdioMCPConnection.ts
│   └── HttpMCPConnection.ts
│
├── tools/             # Tool implementations
│   ├── WebFetchTool.ts      # Secure web fetching
│   └── ToolRegistry.ts      # Tool management + parallel execution
│
├── services/          # External services
│   └── GeminiAIService.ts   # Gemini API (with thinkingConfig, image generation)
│
├── handlers/          # MCP tool handlers
│   ├── QueryHandler.ts
│   ├── SearchHandler.ts
│   ├── FetchHandler.ts
│   └── ImageGenerationHandler.ts  # Image generation via Gemini image models
│
├── managers/          # Business logic
│   └── ConversationManager.ts
│
├── errors/            # Custom error types
├── types/             # TypeScript type definitions
├── schemas/           # Zod validation schemas (including ImageGenerationSchema)
├── config/            # Configuration loading
├── utils/             # Shared utilities (Logger, security, imageSaver)
│
└── server/            # MCP server bootstrap
    └── GeminiAIMCPServer.ts

See DIRECTORY_STRUCTURE.md and ARCHITECTURE.md for details.

Advanced Usage

External MCP Servers

Connect to external MCP servers for extended capabilities:

Stdio (subprocess):

export GEMINI_MCP_SERVERS='[
  {
    "name": "filesystem",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "./workspace"]
  }
]'

HTTP:

export GEMINI_MCP_SERVERS='[
  {
    "name": "api-server",
    "transport": "http",
    "url": "https://api.example.com/mcp",
    "headers": {"Authorization": "Bearer token"}
  }
]'

Tools from external servers are automatically discovered and made available to the agent.

Reasoning Traces

Default: Console Logging

Logs are sent to stderr by default, making them visible in MCP client logs.

For File-Based Logging:

export GEMINI_LOG_TO_STDERR="false"        # Disable console, use files
export GEMINI_LOG_DIR="./logs"             # Log directory (default: ./logs)

Then check logs:

tail -f logs/general.log     # All logs
tail -f logs/reasoning.log   # Gemini thinking process only

To Disable All Logging:

export GEMINI_DISABLE_LOGGING="true"

Custom Tool Development

Tools follow MCP standard:

import { BaseTool, ToolResult, RunContext } from './agentic/Tool.js';

export class MyTool extends BaseTool {
  name = 'my_tool';
  description = 'Description for LLM';
  parameters = {
    type: 'object',
    properties: {
      arg: { type: 'string', description: 'Argument' }
    },
    required: ['arg']
  };

  async execute(args: any, context: RunContext): Promise<ToolResult> {
    // Your implementation
    return {
      status: 'success',
      content: 'Result'
    };
  }
}

Development

Build

npm run build

Watch Mode

npm run watch

Development Mode

npm run dev

Troubleshooting

MCP Server Connection Issues

If the MCP server appears to be "dead" or disconnects unexpectedly:

Check MCP client logs (logs are sent to stderr by default):

  • macOS: ~/Library/Logs/Claude/mcp*.log

  • Windows: %APPDATA%\Claude\Logs\mcp*.log

Server logs will appear in these files automatically.

Log Directory Errors

If you encounter errors like ENOENT: no such file or directory, mkdir './logs':

This should not happen with default settings (console logging is default).

If you enabled file logging (GEMINI_LOG_TO_STDERR="false"):

Solution: Use a writable log directory:

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "github:mnthe/gemini-mcp-server"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id",
        "GEMINI_LOG_TO_STDERR": "false",
        "GEMINI_LOG_DIR": "/tmp/gemini-logs"
      }
    }
  }
}

Authentication Errors

  1. Verify credentials: gcloud auth application-default login

  2. Check project ID: echo $GOOGLE_CLOUD_PROJECT

  3. Enable Vertex AI API: gcloud services enable aiplatform.googleapis.com

Tool Execution Failures

  • Check logs in logs/general.log (if logging is enabled)

  • Verify MCP server configurations in GEMINI_MCP_SERVERS

  • Ensure external servers are running (for HTTP transport)

MaxTurns Exceeded

  • Agent returns best-effort response after 10 turns

  • Check if tools are repeatedly failing

  • Review reasoning logs to understand loop behavior (if logging is enabled)

Documentation

Available Tools

10 tools
check_videoA

Check the status of a video generation operation. Returns status: 'running' (still generating), 'completed' (with saved file paths), or 'failed' (with error). If status is 'running', wait ~30 seconds before checking again. Completed videos are saved to /root/Videos/gemini-generated.

ParametersJSON Schema
NameRequiredDescriptionDefault
operationIdYesOperation ID returned by generate_video

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It fully discloses polling behavior, possible statuses ('running', 'completed', 'failed'), and the output location for completed videos. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words, key information front-loaded. Efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one parameter, no output schema), the description is complete. It covers purpose, behavior, polling guidance, and output location. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the single parameter 'operationId' with 100% coverage. The description adds context by linking it to generate_video, which is helpful. While it doesn't add extensive new information, it clarifies usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks the status of a video generation operation. It distinguishes from sibling tools like generate_video, which initiates an operation, by focusing on polling for completion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (after generate_video) and provides polling guidance (wait ~30 seconds if status is 'running'). It does not explicitly state when not to use it, but the context makes it clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetchC

Fetch the full contents of a search result document by its ID. Follows OpenAI MCP specification for fetch tools.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesThe unique identifier for the document to fetch

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits. It only states 'Fetch the full contents' but does not mention whether the tool is read-only, any authentication requirements, rate limits, or error behavior. The description is insufficient for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and to the point, consisting of two sentences. However, the second sentence ('Follows OpenAI MCP specification...') is unnecessary and provides no actionable information, slightly reducing efficiency. Still, it is appropriately sized for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple fetch tool with one required parameter and no output schema, the description is moderately complete. It lacks information about return format, error conditions, or when to use this tool over siblings. Given the minimal context from other fields, a more detailed description would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter 'id', so the schema already documents it. The description adds no additional semantic value (e.g., format constraints, examples) beyond reiterating that the ID identifies the document.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (fetch), the resource (full contents of a search result document), and the means (by ID). It is specific and distinguishes this tool from siblings like query or search, though it does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description only mentions following the OpenAI MCP specification, which is vague and provides no practical usage context or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageA

Generate images using Gemini's native image generation (Nano Banana). Supports gemini-3-pro-image, gemini-3.1-flash-image, gemini-3.1-flash-lite-image, and gemini-2.5-flash-image models. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fast, low-cost GA tier: 1K output only, standard aspect ratios (no 1:4/1:8/4:1/8:1), no thinkingLevel, up to 14 reference images. gemini-3.1-flash-image is required for 0.5K and 1:4/1:8/4:1/8:1 ratios. gemini-2.5-flash-image (legacy, retires 2026-10-02) supports at most 3 reference images and does not support imageSize. Reference images use imagePaths and must be PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp), HEIC (.heic), HEIF (.heif). Audio and video reference files are not accepted by generate_image. Images are saved to /root/Pictures/gemini-generated and returned as base64.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoImage model (default: gemini-3-pro-image). gemini-3.1-flash-lite-image = fast/low-cost GA tier (1K only, no thinkingLevel, no 1:4/1:8/4:1/8:1 ratios). gemini-2.5-flash-image = legacy (at most 3 reference images, no imageSize, retires 2026-10-02) — prefer gemini-3.1-flash-lite-image.
promptYesImage generation prompt
imageSizeNoResolution (0.5K requires gemini-3.1-flash-image; gemini-3.1-flash-lite-image supports 1K only; default: 1K)
imagePathsNoLocal file paths of reference images to include as input (max 14; gemini-2.5-flash-image supports at most 3). Supported file types: PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp), HEIC (.heic), HEIF (.heif). Audio/video files are not accepted.
aspectRatioNoAspect ratio (default: 1:1; 1:4, 1:8, 4:1, and 8:1 require gemini-3.1-flash-image)
thinkingLevelNoOptional thinking level; only supported by gemini-3.1-flash-image
mediaResolutionNoOptional media resolution for reference image inputs
systemInstructionNoOptional system instruction for Gemini 3 image models

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses behavioral traits: supported models, constraints per model (e.g., max reference images, supported resolutions/aspect ratios), file types, output location, and base64 return. Lacks info on auth, rate limits, but is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Information is well-structured and front-loaded. Slightly long but every sentence adds value. Could be trimmed slightly without loss of clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 8 parameters and no output schema, description covers model differences, constraints, output location, and return format. Lacks error handling details but is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and description adds extra context (e.g., model tiers, limitations, supported file types) that goes beyond schema descriptions, enriching parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Generate images using Gemini's native image generation' and lists specific models. Distinguishes from sibling tools like generate_speech and generate_video by focusing on image generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides detailed guidance on which model to use for specific needs (e.g., fast/low-cost tier, required model for certain resolutions/aspect ratios). However, does not explicitly compare against sibling tools like generate_video, but context makes it clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_musicA

Generate music using Lyria models. Supports lyria-3-clip-preview fixed 30-second clips and lyria-3-pro-preview full songs up to 184 seconds. Lyria 3 supports one clip per prompt; language directions follow the model-card set: English, German, Spanish, French, Hindi, Japanese, Korean, Portuguese. Gemini API/AI Studio mode supports 44.1 kHz stereo audio/mp3 output, and audio/wav only for lyria-3-pro-preview. Negative prompting is not supported. Lyria 3 accepts text prompts and optional imagePaths (PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp), HEIC (.heic), HEIF (.heif)); audio/video reference files are not accepted. Audio is saved to /root/Music/gemini-generated/music and returned as MCP audio content.

ParametersJSON Schema
NameRequiredDescriptionDefault
bpmNoOptional tempo direction in beats per minute
modelNoMusic model (default: lyria-3-clip-preview)
lyricsNoOptional user-provided lyrics to include in the Lyria prompt
promptYesMusic generation prompt
languageNoOptional output language direction. Supported Lyria 3 languages: English, German, Spanish, French, Hindi, Japanese, Korean, Portuguese
intensityNoOptional musical intensity direction
imagePathsNoOptional local image paths to use as multimodal music generation inputs (max 10). Supported Gemini image input file types: PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp), HEIC (.heic), HEIF (.heif). Audio/video reference files are not accepted by Lyria 3.
vocalStyleNoOptional vocal generation direction, such as vocal tone, language, or delivery style
instrumentalNoExplicitly request instrumental-only output
outputMimeTypeNoOptional output MIME type; Gemini API/AI Studio defaults to audio/mp3 and supports audio/wav only with lyria-3-pro-preview
durationSecondsNoOptional target duration in seconds; requires lyria-3-pro-preview; maximum 184 seconds. lyria-3-clip-preview is fixed at 30 seconds

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations, so description must fully disclose behavior. It covers clip duration, generation limits, language support, output MIME types, image input formats, output path, and return type as MCP audio content. Very transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is dense but efficient; every sentence adds value. Could be slightly more structured (e.g., separate paragraphs for models, inputs, outputs), but not overly long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 11 parameters and no output schema, the description covers all key aspects: model variants, duration limits, languages, input types, output path, and return type. No missing critical information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage, yet description adds significant value: explains fixed 30s for clip vs pro, audio specifications (44.1 kHz, stereo), and limitations (no negative prompting, audio/video refs not accepted). Enhances schema meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Generate music using Lyria models' – a specific verb+resource. Distinguishes from siblings like generate_image, generate_speech, etc., which are for different modalities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides detailed guidance on model selection (clip vs pro), language directions, output formats, and limitations (no negative prompting, no audio/video references). Does not explicitly state when not to use, but covers context well.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_omni_videoA

Generate or conversationally edit short videos with Gemini Omni Flash (gemini-omni-flash-preview). This is a NON-Veo model on the Google AI Studio (Gemini API) backend and does NOT use generate_video/check_video: it returns the finished video synchronously in one call (no operationId polling). Two paths: (1) ONESHOT generation — text-to-video, or image/reference-to-video via imagePaths (max 7); (2) INTERACTIVE editing — set previousInteractionId to an id returned by a prior call to edit that video with a natural-language instruction (no image re-upload; chain up to 3 sequential edits). Constraints: 720p output only; aspect ratio 16:9 or 9:16; clips run a few seconds (steer pacing/timing within the prompt — duration is not a parameter); a synced audio track is generated automatically (audio reference inputs are not accepted — describe dialogue/SFX/ambience in the prompt). Image source file types: PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp). The response includes interactionId (pass it back as previousInteractionId to edit) and the saved file path. Videos are saved to /root/Videos/gemini-generated.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoOmni video model (default: gemini-omni-flash-preview)
promptYesVideo prompt for a new generation (oneshot), or a natural-language edit instruction when previousInteractionId is set (interactive editing). Describe dialogue/SFX/ambience as text; audio reference files are not accepted.
imagePathsNoLocal file paths of source/reference images for image-to-video or reference-to-video (max 7). Supported file types: PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp). Omit for interactive edits — previousInteractionId reuses the prior video.
aspectRatioNoAspect ratio (default: 16:9). Omni Flash supports 16:9 and 9:16 only. Output is 720p only.
previousInteractionIdNoInteraction ID from a prior generate_omni_video call. When set, conversationally edits that video (no image re-upload) instead of generating a new one.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses key behaviors: synchronous execution (no polling), 720p output, auto-generated audio, no audio input, supported image types, and response fields (interactionId, file path). No contradictions exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-organized, front-loading the core purpose and then detailing paths, constraints, and response. While slightly verbose, every sentence adds value. Minor conciseness improvements could be made.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains the response format (interactionId, saved file path). It covers all necessary aspects: model, modes, inputs, constraints, process, and output. It also differentiates from sibling tools effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds meaningful context beyond the schema, such as the dual role of prompt (oneshot vs. edit), the omission of imagePaths for edits, and the 720p constraint for aspectRatio.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates or conversationally edits short videos using Gemini Omni Flash, distinguishing it from sibling tools like generate_video (which uses a different model and polling). It specifies two distinct paths (oneshot and interactive editing) and lists key capabilities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is provided on when to use each path: oneshot for new video (text-to-video or with images) and interactive editing by setting previousInteractionId. Constraints like max 7 images, no audio references, and supported aspect ratios are clearly stated, and it implicitly distinguishes from sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_speechA

Generate speech audio using Gemini TTS models. Supports single-speaker and two-speaker TTS. Input is text-only; audio, image, and video reference files are not accepted. TTS has a 32k-token context limit and does not support streaming. Audio is saved to /root/Music/gemini-generated/speech and returned as MCP audio content.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoSpeech model (default: gemini-3.1-flash-tts-preview, valid on both backends). Vertex AI uses GA ids gemini-2.5-flash-tts/gemini-2.5-pro-tts; Google AI Studio uses gemini-2.5-flash-preview-tts/gemini-2.5-pro-preview-tts.
promptYesText or transcript to synthesize as speech. Gemini TTS is text-only input; audio/image/video reference files are not accepted.
speakersNoExactly two speaker voice configs for multi-speaker TTS
voiceNameNoPrebuilt voice name for single-speaker TTS (default: Kore)
languageCodeNoOptional BCP-47 language code for speech synthesis

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility. It discloses key behaviors: text-only input, 32k-token limit, no streaming, output saved to a specific path and returned as MCP audio content.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences encapsulate all essential information without redundancy. The most critical purpose is front-loaded, making it easy for an agent to quickly grasp the tool's function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 5 parameters and no output schema, the description covers input constraints, output location, and return type. It could mention output length or multi-speaker prompt formatting, but overall it's sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining model defaults, backend-specific IDs, and the nature of the speakers array, exceeding baseline expectations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it generates speech audio using Gemini TTS models, specifying support for single and two-speaker. It distinguishes from sibling tools like generate_music or generate_video by focusing on text-to-speech.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: input is text-only, no audio/image/video references, 32k-token limit, no streaming. While it doesn't explicitly contrast with alternatives, it clearly defines when this tool is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_videoA

Start video generation using Google's Veo models. Returns an operationId immediately. Video generation typically takes 1-3 minutes. Use check_video with the operationId to poll for completion and download results. Recommended polling interval: 30 seconds. Supports text-to-video, image-to-video (with imagePath), interpolation (imagePath + lastFramePath), reference images (referenceImagePaths, max 3, Veo 3.1 only), and Veo video extension (videoPath). Image source file types: PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp). videoPath must be MP4 (.mp4) from a previous Veo 720p generation. Audio file references are not supported; describe dialogue, SFX, and ambience in the prompt instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoRandom seed for reproducibility
modelNoVideo model (default: veo-3.1-fast-generate-preview)
promptYesVideo generation prompt. Include dialogue, SFX, and ambience as text audio cues; audio reference files are not accepted.
imagePathNoLocal file path of input image for image-to-video generation. Supported file types: PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp)
videoPathNoLocal file path of a Veo-generated 720p input video to extend. Supported file types: MP4 (.mp4) from a previous Veo 720p generation
resizeModeNoHow the input image is fit to the target aspect ratio for image-to-video (Vertex AI only; requires imagePath): 'crop' or 'pad' (default pad)
resolutionNoVideo resolution (1080p/4k requires 8s duration, default: 720p)
aspectRatioNoAspect ratio (default: 16:9)
enhancePromptNoUse Veo prompt rewriting/enhancement
generateAudioNoNot configurable in Gemini Developer API mode; Veo 3.1 audio is always on
lastFramePathNoLocal file path of last frame image for interpolation (requires imagePath). Supported file types: PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp)
negativePromptNoText describing what to exclude from the video
numberOfVideosNoNumber of videos to generate (default: 1, max: 1)
durationSecondsNoVideo duration in seconds (default: 8)
personGenerationNoOptional person generation control
compressionQualityNoOutput video compression quality (Vertex AI only): 'optimized' (smaller file, default) or 'lossless' (larger, highest quality)
referenceImagePathsNoLocal file paths of reference images for style/asset guidance (max 3, Veo 3.1 only). Supported file types: PNG (.png), JPEG (.jpg/.jpeg), WEBP (.webp)

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses that generation takes 1-3 minutes, returns an operationId immediately, and lists limitations like 'Audio file references are not supported'. It is transparent about async behavior but could mention authentication requirements or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, well-structured paragraph. It front-loads the essential action ('Returns an operationId immediately') and then provides detailed options and constraints without redundancy. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 17 parameters and no output schema, the description covers the necessary context: modes, polling workflow, unsupported features, file types, and combination rules. It equips the agent to select and invoke the tool appropriately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds significant value by summarizing common usage patterns (text-to-video, image-to-video, interpolation) and providing constraints (e.g., 'videoPath must be MP4 from a previous Veo 720p generation'). This helps the agent understand parameter relationships beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it starts video generation using Google's Veo models, specifying multiple modes (text-to-video, image-to-video, etc.). It distinguishes itself from sibling tools like generate_image and check_video by focusing on video generation and referencing the polling workflow.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit instructions: 'Use check_video with the operationId to poll for completion' and recommends a 30-second polling interval. It also clarifies what is not supported (audio file references). However, it does not explicitly state when to avoid this tool in favor of alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

queryA

Query Google AI (Gemini models) with a prompt. This tool operates as an intelligent agent with multi-turn execution capabilities. The agent can automatically use available tools (web fetching, external MCP servers) to gather information and provide comprehensive answers. Supports multi-turn conversations when sessionId is provided. Supports multimodal inputs (images, audio, video, documents) via the optional 'parts' parameter.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoOptional model override (e.g., gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3.1-pro-preview, gemini-3.1-pro-preview-customtools)
partsNoOptional multimodal content parts (images, audio, video, documents)
promptYesThe prompt to send to Gemini
sessionIdNoOptional conversation session ID for multi-turn conversations
thinkingLevelNoOptional Gemini 3 thinking level override
mediaResolutionNoOptional global media resolution for multimodal inputs

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries the burden. It discloses multi-turn execution, automatic tool use, and multimodal support, but omits safety traits like cost, rate limits, error handling, or latency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with main purpose, followed by key capabilities. Minor redundancy (e.g., multi-turn and multimodal mentions), but overall efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers core functionality but lacks output format details (e.g., response structure) and limits on tool calls. Given complexity and no output schema, more detail would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline 3 applies. Description adds no extra meaning beyond schema descriptions (e.g., model, parts, sessionId are already explained in schema).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it queries Google AI (Gemini models) with a prompt, specifying it as an intelligent agent with multi-turn and multimodal capabilities. It differentiates from sibling tools like 'search' (direct search) and 'generate_image' (media generation) by emphasizing agentic reasoning and automatic tool use.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage for complex queries requiring multi-step reasoning and automatic tool use, contrasting with siblings. Context is clear but lacks explicit when-not scenarios or direct comparisons, e.g., when to use 'search' instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 10 tool updatesv1.0.0
    • First observedcheck_video
    • First observedfetch
    • First observedgenerate_image
    • First observedgenerate_music
    • First observedgenerate_omni_video
    • First observedgenerate_speech
    • First observedgenerate_video
    • First observedquery
    • First observedreference_search
    • First observedsearch
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: query for conversational AI, search/fetch for web retrieval, generate_image for image generation, generate_video/check_video for async video, generate_omni_video for sync video, generate_speech for TTS, generate_music for music, and reference_search for grounded Q&A. No two tools overlap in functionality.

Naming Consistency5/5

All tool names follow the verb_noun pattern (e.g., generate_image, check_video, reference_search) using imperative verbs and underscores consistently. No camelCase or mixed conventions.

Tool Count5/5

10 tools cover the server's multi-modal AI capabilities (text, web, images, videos, audio) without bloat. Each tool provides a necessary function, and the count is well-balanced for a comprehensive generative AI server.

Completeness5/5

The tool set covers the full lifecycle for each modality: generation, status checks where needed (via check_video for async video), and multiple generation backends (e.g., two video models). The query tool serves as a general-purpose agent. No obvious missing operations for the declared scope.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Gemini Chat MCP

    LNS2905
    F
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables chatting with Google Gemini AI models and custom Gems, supporting text and image generation with automatic cookie synchronization via Chrome extension.
    3
    -

  • Gemini Search MCP

    kidapu
    A
    license
    B
    quality
    D
    maintenance
    Enables AI-powered web searches using Google's Gemini 2.5 models with Google Search Grounding. Supports multiple Gemini models (Flash, Flash-Lite, Pro) with configurable thinking budget and web search capabilities.
    1
    16
    2
    MIT

  • Gemini MCP Server

    xumingjun5208
    A
    license
    A
    quality
    D
    maintenance
    Enables multi-turn conversations with Google Gemini AI models, supporting file and image analysis, automatic model selection, deep thinking mode, and Google Search integration through the AIStudioProxyAPI backend.
    2
    2
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mnthe/gemini-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server