Skip to main content
Glama

MCP Gemini CrunchTools

A secure MCP (Model Context Protocol) server for Google Gemini AI - text, image, video, research, and more.

Overview

This MCP server is designed to be:

  • Secure by default - STRIDE threat model (see SECURITY.md), Pydantic input validation, and the API key held as a SecretStr to prevent accidental logging

  • No third-party services - Runs locally via stdio, your API key never leaves your machine

  • Cross-platform - Works on Linux, macOS, and Windows

  • Automatically updated - GitHub Actions monitor for CVEs and update dependencies

  • Containerized - Available at quay.io/crunchtools/mcp-gemini built on Hummingbird Python base image

Related MCP server: Gemini Research MCP Server

Naming Convention

Component

Name

GitHub repo

crunchtools/mcp-gemini

Container

quay.io/crunchtools/mcp-gemini

Python package (PyPI)

mcp-gemini-crunchtools

CLI command

mcp-gemini-crunchtools

Module import

mcp_gemini_crunchtools

Why Hummingbird?

The container image is built on the Hummingbird Python base image from Project Hummingbird, which provides:

  • Minimal CVE exposure - Hummingbird images are built with a minimal package set, dramatically reducing the attack surface compared to general-purpose images

  • Regular updates - Security patches are applied promptly, keeping CVE counts low

  • Optimized for Python - Pre-configured Python environment with uv package manager for fast, reproducible builds

  • Production-ready - Designed for production workloads with proper signal handling and non-root user defaults

This means your MCP server runs in a hardened environment with fewer vulnerabilities than typical Python container images.

Features

Query Tools (5 tools)

  • gemini_query - Query Gemini with optional Google Search grounding

  • gemini_brainstorm - Generate creative ideas on a topic

  • gemini_analyze_code - Analyze code for security, performance, bugs

  • gemini_analyze_text - Analyze text for sentiment, tone, content

  • gemini_summarize - Summarize content in various formats

Image Generation (4 tools)

  • gemini_generate_image - Generate images from text prompts (native Gemini)

  • gemini_generate_image_with_input - Edit/modify existing images

  • gemini_image_prompt - Craft effective image generation prompts

  • gemini_imagen_generate - Generate images using Google Imagen 4 models

Image Editing (4 tools)

  • gemini_start_image_edit - Start a multi-turn image editing session

  • gemini_continue_image_edit - Continue editing in an active session

  • gemini_end_image_edit - End an image editing session

  • gemini_list_image_sessions - List all active editing sessions

Image Analysis (1 tool)

  • gemini_analyze_image - Analyze and describe local image files

Search Tools (1 tool)

  • gemini_search - Web search using Gemini with Google Search grounding

Document Tools (3 tools)

  • gemini_analyze_document - Analyze PDFs, DOCX, TXT, etc.

  • gemini_summarize_pdf - Summarize PDF documents

  • gemini_extract_tables - Extract tables from documents

URL Tools (3 tools)

  • gemini_analyze_url - Analyze one or more URLs

  • gemini_compare_urls - Compare two URLs

  • gemini_extract_from_url - Extract specific data from a URL

Video Tools (2 tools)

  • gemini_generate_video - Generate videos using Veo

  • gemini_check_video - Check video generation status

YouTube Tools (2 tools)

  • gemini_youtube - Analyze YouTube videos

  • gemini_youtube_summary - Summarize YouTube videos

Voice Tools (3 tools)

  • gemini_speak - Convert text to speech

  • gemini_dialogue - Generate multi-voice dialogue audio

  • gemini_list_voices - List available voices

Research Tools (3 tools)

  • gemini_deep_research - Perform multi-step web research

  • gemini_check_research - Check research operation status

  • gemini_research_followup - Ask follow-up questions

Cache Tools (4 tools)

  • gemini_create_cache - Create content cache for repeated queries

  • gemini_query_cache - Query cached content

  • gemini_list_caches - List all active caches

  • gemini_delete_cache - Delete a cache

Structured Output Tools (2 tools)

  • gemini_structured - Get structured JSON output

  • gemini_extract - Extract structured data from text

Token Tools (1 tool)

  • gemini_count_tokens - Count tokens in content

Code Execution Tools (1 tool)

  • gemini_run_code - Execute Python code via Gemini

Total: 39 tools

Installation

uvx mcp-gemini-crunchtools

With pip

pip install mcp-gemini-crunchtools

With Container

# Create a shared output directory (required before first run)
mkdir -p ~/.local/share/mcp-uploads-downloads

podman run -v ~/.local/share/mcp-uploads-downloads:/output:z \
    -e GEMINI_API_KEY=your_key \
    -e GEMINI_OUTPUT_DIR=/output \
    quay.io/crunchtools/mcp-gemini

SELinux note: Use :z (lowercase, shared) instead of :Z (uppercase, private). MCP servers run as long-lived stdio processes. With :Z, files copied into the directory after container start won't have the container's private MCS label and will be invisible inside the container. The :z flag sets a shared container_file_t context that all containers and the host can read/write.

Tip: Use the same shared directory (~/.local/share/mcp-uploads-downloads/) across multiple MCP container servers (e.g., mcp-gemini and mcp-wordpress) so generated images are immediately available for WordPress upload without copying.

Configuration

Creating a Google Gemini API Key

  1. Navigate to Google AI Studio

  2. Create API Key

    • Click "Get API key" or "Create API key"

    • Select a Google Cloud project or create a new one

    • Click "Create API key in new project" (or select existing project)

  3. Copy Your API Key

    • IMPORTANT: Copy the API key immediately - store it securely!

    • The key starts with AI... (e.g., AIzaSy...)

Add to Claude Code

claude mcp add mcp-gemini-crunchtools \
    --env GEMINI_API_KEY=your_api_key_here \
    -- uvx mcp-gemini-crunchtools

Or for the container version:

# Create a shared output directory (required before first run)
mkdir -p ~/.local/share/mcp-uploads-downloads

claude mcp add mcp-gemini-crunchtools \
    --env GEMINI_API_KEY=your_api_key_here \
    --env GEMINI_OUTPUT_DIR=/output \
    -- podman run -i --rm \
        -v ~/.local/share/mcp-uploads-downloads:/output:z \
        -e GEMINI_API_KEY \
        -e GEMINI_OUTPUT_DIR=/output \
        quay.io/crunchtools/mcp-gemini

Keep the API key out of config files (GEMINI_API_KEY_FILE)

--env GEMINI_API_KEY=... stores the key in plaintext in Claude Code's config, and -e GEMINI_API_KEY exposes it in podman inspect. Instead, store the key in a file and pass only its path. GEMINI_API_KEY takes precedence; the file is read only when it is unset.

mkdir -p ~/.config/mcp-gemini && chmod 700 ~/.config/mcp-gemini
( umask 077; read -rsp "Gemini API key: " key && printf '%s' "$key" > ~/.config/mcp-gemini/api-key; rc=$?; unset key; exit $rc )

claude mcp add mcp-gemini-crunchtools \
    --env GEMINI_API_KEY_FILE=$HOME/.config/mcp-gemini/api-key \
    -- uvx mcp-gemini-crunchtools

# Containers: mount as a read-only secret
podman run -i --rm \
    -v ~/.config/mcp-gemini/api-key:/run/secrets/api-key:ro,z \
    -e GEMINI_API_KEY_FILE=/run/secrets/api-key \
    quay.io/crunchtools/mcp-gemini

Optional: Set Output Directory (non-container)

For generated images, audio, and videos when running without a container:

claude mcp add mcp-gemini-crunchtools \
    --env GEMINI_API_KEY=your_api_key_here \
    --env GEMINI_OUTPUT_DIR=$HOME/.local/share/mcp-uploads-downloads \
    -- uvx mcp-gemini-crunchtools

Usage Examples

User: What are the latest developments in quantum computing?
Assistant: [calls gemini_query with use_google_search=true]

Generate an Image

User: Generate a photorealistic image of a sunset over mountains
Assistant: [calls gemini_generate_image with prompt and style]

Analyze a PDF Document

User: Analyze this research paper at /path/to/paper.pdf
Assistant: [calls gemini_analyze_document with file_path]

Summarize a YouTube Video

User: Summarize this YouTube video: https://youtube.com/watch?v=...
Assistant: [calls gemini_youtube_summary with url]

Deep Research

User: Research the environmental impact of electric vehicles
Assistant: [calls gemini_deep_research then gemini_check_research]

Code Analysis

User: Analyze this Python code for security issues
Assistant: [calls gemini_analyze_code with focus="security"]

Security

This server was designed with security as a primary concern. See SECURITY.md for:

  • Threat model and attack vectors

  • Defense in depth architecture

  • API key handling best practices

  • Input validation rules

  • Audit logging

Key Security Features

  1. API Key Protection

    • Stored as SecretStr (never accidentally logged)

    • Environment variable only (never in files or args)

    • Sanitized from all error messages

  2. Input Validation

    • Pydantic models for all inputs

    • File path validation

    • URL validation

    • Strict format validation

  3. API Hardening

    • Hardcoded API base URL (prevents SSRF)

    • TLS certificate validation

    • Request timeouts

    • Response size limits

  4. Automated CVE Scanning

    • GitHub Actions scan dependencies weekly

    • Automatic PRs for security updates

    • Dependabot alerts enabled

Development

Setup

git clone https://github.com/crunchtools/mcp-gemini.git
cd mcp-gemini
uv sync

Run Tests

uv run pytest

Lint and Type Check

uv run ruff check src tests
uv run mypy src

Build Container

podman build -t mcp-gemini .

License

AGPL-3.0-or-later

Contributing

Contributions welcome! Please read SECURITY.md before submitting security-related changes.

Available Tools

39 tools
gemini_analyze_code_toolGemini Analyze Code ToolC
Read-only

Analyze code with Gemini.

Inputs: code (required), focus, model, language. Returns: object

gemini_analyze_document_toolGemini Analyze Document ToolC

Analyze a document (PDF, DOCX, TXT, etc.).

Inputs: file_path (required), model, question. Returns: object

gemini_analyze_image_toolGemini Analyze Image ToolC
Read-only

Analyze and describe a local image file.

Inputs: image_path (required), model, query. Returns: object

gemini_analyze_text_toolGemini Analyze Text ToolC
Read-only

Analyze text with Gemini.

Inputs: text (required), model, analysis_type. Returns: object

gemini_analyze_url_toolGemini Analyze Url ToolC
Read-only

Analyze one or more URLs.

Inputs: urls (required), model, question, use_google_search. Returns: object

gemini_brainstorm_toolGemini Brainstorm ToolC
Read-only

Brainstorm ideas on a topic using Gemini.

Inputs: topic (required), model, context, num_ideas. Returns: object

gemini_check_research_toolGemini Check Research ToolC
Read-only

Check the status of a deep research operation.

Inputs: research_id (required). Returns: object

gemini_check_video_toolGemini Check Video ToolB
Read-only

Check the status of a video generation operation.

Inputs: operation_name (required). Returns: object

gemini_compare_urls_toolGemini Compare Urls ToolC
Read-only

Compare two URLs.

Inputs: url1 (required), url2 (required), model, aspect. Returns: object

gemini_continue_image_edit_toolGemini Continue Image Edit ToolC

Continue editing in an active image session.

Inputs: prompt (required), session_id (required). Returns: object

gemini_count_tokens_toolGemini Count Tokens ToolB
Read-only

Count the number of tokens in content.

Inputs: content (required), model. Returns: object

gemini_create_cache_toolGemini Create Cache ToolB

Create a content cache for repeated queries.

Upload content once and query it multiple times without re-sending.

Inputs: model, content, file_path, ttl_minutes, +2 more. Returns: object

gemini_deep_research_toolGemini Deep Research ToolB

Start a deep research task using a specialized Gemini model.

Performs multi-step web research to answer complex questions. Completes in a single call; the result is returned immediately.

Inputs: query (required). Returns: object

gemini_delete_cache_toolGemini Delete Cache ToolC

Delete a content cache.

Inputs: cache_name (required). Returns: object

gemini_dialogue_toolGemini Dialogue ToolC

Generate multi-voice dialogue audio.

Inputs: text (required), voice1, voice2. Returns: object

gemini_end_image_edit_toolGemini End Image Edit ToolB

End an image editing session and free resources.

Inputs: session_id (required). Returns: object

gemini_extract_from_url_toolGemini Extract From Url ToolC
Read-only

Extract specific data from a URL.

Inputs: url (required), model, data_type, custom_fields. Returns: object

gemini_extract_tables_toolGemini Extract Tables ToolC

Extract tables from a document.

Inputs: file_path (required), model, output_format. Returns: object

gemini_extract_toolGemini Extract ToolC
Read-only

Extract structured data from text.

Inputs: text (required), model, extract_type, custom_fields. Returns: object

gemini_generate_image_toolGemini Generate Image ToolB

Generate an image from a text prompt using Gemini's native image model.

Inputs: prompt (required), style, image_size, aspect_ratio, +1 more. Returns: object

gemini_generate_image_with_input_toolGemini Generate Image With Input ToolA

Generate/edit an image using a local image file as input.

Upload a local image and give Gemini instructions for how to modify it. Use cases: add watermarks, change styles, composite images, etc.

Inputs: prompt (required), file_path (required), _aspect_ratio. Returns: object

gemini_generate_video_toolGemini Generate Video ToolB

Generate a video using Veo. Returns an operation ID to poll.

Inputs: prompt (required), _aspect_ratio, negative_prompt. Returns: object

gemini_imagen_generate_toolGemini Imagen Generate ToolA

Generate images using Google Imagen 4 models.

Models (sorted by price):

  • imagen-4.0-fast-generate-001 ($0.02/image, fastest)

  • imagen-4.0-generate-001 ($0.04/image, standard)

  • imagen-4.0-ultra-generate-001 ($0.06/image, highest quality)

Inputs: prompt (required), model, aspect_ratio, number_of_images. Returns: object

gemini_image_prompt_toolGemini Image Prompt ToolC
Read-only

Help craft an effective image generation prompt.

Inputs: description (required), mood, model, style. Returns: object

gemini_list_caches_toolGemini List Caches ToolB
Read-only

List all active content caches.

Inputs: no named parameters. Returns: object

gemini_list_image_sessions_toolGemini List Image Sessions ToolB

List all active image editing sessions.

Inputs: no named parameters. Returns: object

gemini_list_voices_toolGemini List Voices ToolA
Read-only

List available voices for text-to-speech.

Inputs: no named parameters. Returns: object

gemini_query_cache_toolGemini Query Cache ToolC
Read-only

Query content in a cache.

Inputs: question (required), cache_name (required). Returns: object

gemini_query_toolGemini Query ToolC
Read-only

Query Gemini with a prompt. Supports Google Search grounding.

Inputs: prompt (required), model, use_google_search, system_instruction. Returns: object

gemini_research_followup_toolGemini Research Followup ToolB
Read-only

Ask a follow-up question about completed research.

Inputs: question (required), research_id (required). Returns: object

gemini_run_code_toolGemini Run Code ToolB

Execute code using Gemini's built-in code execution.

Gemini writes and runs Python code to answer questions, perform calculations, or process data.

Inputs: prompt (required), data, model. Returns: object

gemini_search_toolGemini Search ToolB
Read-only

Search the web using Gemini with Google Search grounding.

Inputs: query (required), model. Returns: object

gemini_speak_toolGemini Speak ToolC

Convert text to speech.

Inputs: text (required), voice. Returns: object

gemini_start_image_edit_toolGemini Start Image Edit ToolA

Start a multi-turn image editing session.

Optionally provide an existing image file as the starting point. Without file_path, Gemini generates a new image from the prompt. Use gemini_continue_image_edit_tool to make further edits.

Inputs: prompt (required), file_path, use_google_search. Returns: object

gemini_structured_toolGemini Structured ToolC
Read-only

Get structured JSON output from Gemini.

Inputs: prompt (required), model, schema, use_google_search. Returns: object

gemini_summarize_pdf_toolGemini Summarize Pdf ToolC

Summarize a PDF document.

Inputs: file_path (required), model, style. Returns: object

gemini_summarize_toolGemini Summarize ToolC
Read-only

Summarize content with Gemini.

Inputs: content (required), model, format, length. Returns: object

gemini_youtube_summary_toolGemini Youtube Summary ToolC
Read-only

Summarize a YouTube video.

Inputs: url (required), model, style. Returns: object

gemini_youtube_toolGemini Youtube ToolC
Read-only

Analyze a YouTube video.

Inputs: url (required), model, question. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 39 tools

    Disambiguation2/5

    Many tools overlap: multiple image generation/editing tools (gemini_generate_image_tool, gemini_imagen_generate_tool, gemini_generate_image_with_input_tool, gemini_start_image_edit_tool), multiple document analysis tools (analyze_document, summarize_pdf, extract_tables), multiple URL tools (analyze_url, compare_urls, extract_from_url), and general query/analyze/summarize/brainstorm tools. Descriptions help but boundaries are fuzzy, risking misselection.

    Naming Consistency4/5

    All tools use snake_case with a consistent 'gemini_' prefix and '_tool' suffix. However, some names lack an action verb (gemini_youtube_tool, gemini_dialogue_tool, gemini_structured_tool) and word order varies (gemini_imagen_generate_tool vs gemini_generate_image_tool), preventing a perfect score.

    Tool Count2/5

    39 tools is well above the recommended 3-15 range and exceeds the 25-tool threshold for 'too many.' While the server covers many modalities, the count suggests redundant or overly granular tooling that could be consolidated.

    Completeness4/5

    The toolset covers a wide range of Gemini capabilities: image/video/audio generation, document/URL/YouTube analysis, research, caching, structured output, token counting, and code execution. Minor gaps exist (e.g., no speech-to-text, no model listing, no embedding generation), but core workflows are well supported.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers