MCP Gemini CrunchTools
Use this server to access Google Gemini AI for text, media, research, and data-processing tasks through MCP.
Query, brainstorm, analyze code/text, summarize, search the web, and perform deep research.
Generate/edit images with Gemini or Imagen, analyze local images, and manage multi-turn image-edit sessions.
Analyze documents/PDFs, extract tables, analyze/compare/extract from URLs, and analyze/summarize YouTube videos.
Generate videos with Veo and check generation status.
Convert text to speech, generate multi-voice dialogue audio, and list available voices.
Create/query/list/delete content caches, get structured JSON, extract structured data, count tokens, and execute Python code via Gemini.
Provides tools for querying Gemini, generating images, analyzing documents, videos, and URLs, performing web research, managing caches, and more via the Google Gemini API.
Provides tools to analyze and summarize YouTube videos.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Gemini CrunchTools Summarize the key points from this PDF document"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
SecretStrto prevent accidental loggingNo 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-geminibuilt on Hummingbird Python base image
Related MCP server: Gemini Research MCP Server
Naming Convention
Component | Name |
GitHub repo | |
Container |
|
Python package (PyPI) |
|
CLI command |
|
Module import |
|
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 groundinggemini_brainstorm- Generate creative ideas on a topicgemini_analyze_code- Analyze code for security, performance, bugsgemini_analyze_text- Analyze text for sentiment, tone, contentgemini_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 imagesgemini_image_prompt- Craft effective image generation promptsgemini_imagen_generate- Generate images using Google Imagen 4 models
Image Editing (4 tools)
gemini_start_image_edit- Start a multi-turn image editing sessiongemini_continue_image_edit- Continue editing in an active sessiongemini_end_image_edit- End an image editing sessiongemini_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 documentsgemini_extract_tables- Extract tables from documents
URL Tools (3 tools)
gemini_analyze_url- Analyze one or more URLsgemini_compare_urls- Compare two URLsgemini_extract_from_url- Extract specific data from a URL
Video Tools (2 tools)
gemini_generate_video- Generate videos using Veogemini_check_video- Check video generation status
YouTube Tools (2 tools)
gemini_youtube- Analyze YouTube videosgemini_youtube_summary- Summarize YouTube videos
Voice Tools (3 tools)
gemini_speak- Convert text to speechgemini_dialogue- Generate multi-voice dialogue audiogemini_list_voices- List available voices
Research Tools (3 tools)
gemini_deep_research- Perform multi-step web researchgemini_check_research- Check research operation statusgemini_research_followup- Ask follow-up questions
Cache Tools (4 tools)
gemini_create_cache- Create content cache for repeated queriesgemini_query_cache- Query cached contentgemini_list_caches- List all active cachesgemini_delete_cache- Delete a cache
Structured Output Tools (2 tools)
gemini_structured- Get structured JSON outputgemini_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
With uvx (Recommended)
uvx mcp-gemini-crunchtoolsWith pip
pip install mcp-gemini-crunchtoolsWith 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-geminiSELinux 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:zflag sets a sharedcontainer_file_tcontext 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
Navigate to Google AI Studio
Sign in with your Google account
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)
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-crunchtoolsOr 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-geminiKeep 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-geminiOptional: 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-crunchtoolsUsage Examples
Query with Google Search
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
API Key Protection
Stored as SecretStr (never accidentally logged)
Environment variable only (never in files or args)
Sanitized from all error messages
Input Validation
Pydantic models for all inputs
File path validation
URL validation
Strict format validation
API Hardening
Hardcoded API base URL (prevents SSRF)
TLS certificate validation
Request timeouts
Response size limits
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 syncRun Tests
uv run pytestLint and Type Check
uv run ruff check src tests
uv run mypy srcBuild Container
podman build -t mcp-gemini .License
AGPL-3.0-or-later
Contributing
Contributions welcome! Please read SECURITY.md before submitting security-related changes.
Links
Available Tools
39 toolsgemini_analyze_code_toolGemini Analyze Code ToolCRead-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 ToolCRead-only
Analyze and describe a local image file.
Inputs: image_path (required), model, query. Returns: object
gemini_analyze_text_toolGemini Analyze Text ToolCRead-only
Analyze text with Gemini.
Inputs: text (required), model, analysis_type. Returns: object
gemini_analyze_url_toolGemini Analyze Url ToolCRead-only
Analyze one or more URLs.
Inputs: urls (required), model, question, use_google_search. Returns: object
gemini_brainstorm_toolGemini Brainstorm ToolCRead-only
Brainstorm ideas on a topic using Gemini.
Inputs: topic (required), model, context, num_ideas. Returns: object
gemini_check_research_toolGemini Check Research ToolCRead-only
Check the status of a deep research operation.
Inputs: research_id (required). Returns: object
gemini_check_video_toolGemini Check Video ToolBRead-only
Check the status of a video generation operation.
Inputs: operation_name (required). Returns: object
gemini_compare_urls_toolGemini Compare Urls ToolCRead-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 ToolBRead-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 ToolCRead-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 ToolCRead-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 ToolCRead-only
Help craft an effective image generation prompt.
Inputs: description (required), mood, model, style. Returns: object
gemini_list_caches_toolGemini List Caches ToolBRead-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 ToolARead-only
List available voices for text-to-speech.
Inputs: no named parameters. Returns: object
gemini_query_cache_toolGemini Query Cache ToolCRead-only
Query content in a cache.
Inputs: question (required), cache_name (required). Returns: object
gemini_query_toolGemini Query ToolCRead-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 ToolBRead-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 ToolBRead-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 ToolCRead-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 ToolCRead-only
Summarize content with Gemini.
Inputs: content (required), model, format, length. Returns: object
gemini_youtube_summary_toolGemini Youtube Summary ToolCRead-only
Summarize a YouTube video.
Inputs: url (required), model, style. Returns: object
gemini_youtube_toolGemini Youtube ToolCRead-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
Scored across 39 tools
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.
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.
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.
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
Related MCP Connectors
Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for Google Veo AI video generation
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseAqualityDmaintenanceA dedicated server that wraps Google's Gemini AI models in a Model Context Protocol (MCP) interface, allowing other LLMs and MCP-compatible systems to access Gemini's capabilities like content generation, function calling, chat, and file handling through standardized tools.1636MIT
- AlicenseAqualityBmaintenanceMCP server for AI-powered research using Gemini. Provides fast grounded web search, deep autonomous research, URL extraction, and session management.988 PyPI10MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for Google Gemini that does not require an API key, combining a CLI backend for Q\&A, research, and analysis with a web UI backend for image and video generation.4 npm3MIT
- AlicenseAqualityCmaintenanceMCP server for Google's Gemini API, enabling text, image, video, speech, embeddings, and deep research capabilities through a single tool set.10MIT