{
  "markdown": "# MCP Gemini CrunchTools\n\nA secure MCP (Model Context Protocol) server for Google Gemini AI - text, image, video, research, and more.\n\n## Overview\n\nThis MCP server is designed to be:\n\n- **Secure by default** - Comprehensive threat modeling, input validation, and API key protection\n- **No third-party services** - Runs locally via stdio, your API key never leaves your machine\n- **Cross-platform** - Works on Linux, macOS, and Windows\n- **Automatically updated** - GitHub Actions monitor for CVEs and update dependencies\n- **Containerized** - Available at `quay.io/crunchtools/mcp-gemini` built on [Hummingbird Python](https://quay.io/repository/hummingbird/python) base image\n\n## Naming Convention\n\n| Component | Name |\n|-----------|------|\n| GitHub repo | [crunchtools/mcp-gemini](https://github.com/crunchtools/mcp-gemini) |\n| Container | `quay.io/crunchtools/mcp-gemini` |\n| Python package (PyPI) | `mcp-gemini-crunchtools` |\n| CLI command | `mcp-gemini-crunchtools` |\n| Module import | `mcp_gemini_crunchtools` |\n\n## Why Hummingbird?\n\nThe container image is built on the [Hummingbird Python base image](https://quay.io/repository/hummingbird/python) from [Project Hummingbird](https://github.com/hummingbird-project), which provides:\n\n- **Minimal CVE exposure** - Hummingbird images are built with a minimal package set, dramatically reducing the attack surface compared to general-purpose images\n- **Regular updates** - Security patches are applied promptly, keeping CVE counts low\n- **Optimized for Python** - Pre-configured Python environment with uv package manager for fast, reproducible builds\n- **Production-ready** - Designed for production workloads with proper signal handling and non-root user defaults\n\nThis means your MCP server runs in a hardened environment with fewer vulnerabilities than typical Python container images.\n\n## Features\n\n### Query Tools (5 tools)\n- `gemini_query` - Query Gemini with optional Google Search grounding\n- `gemini_brainstorm` - Generate creative ideas on a topic\n- `gemini_analyze_code` - Analyze code for security, performance, bugs\n- `gemini_analyze_text` - Analyze text for sentiment, tone, content\n- `gemini_summarize` - Summarize content in various formats\n\n### Image Generation (4 tools)\n- `gemini_generate_image` - Generate images from text prompts (native Gemini)\n- `gemini_generate_image_with_input` - Edit/modify existing images\n- `gemini_image_prompt` - Craft effective image generation prompts\n- `gemini_imagen_generate` - Generate images using Google Imagen 4 models\n\n### Image Editing (4 tools)\n- `gemini_start_image_edit` - Start a multi-turn image editing session\n- `gemini_continue_image_edit` - Continue editing in an active session\n- `gemini_end_image_edit` - End an image editing session\n- `gemini_list_image_sessions` - List all active editing sessions\n\n### Image Analysis (1 tool)\n- `gemini_analyze_image` - Analyze and describe local image files\n\n### Search Tools (1 tool)\n- `gemini_search` - Web search using Gemini with Google Search grounding\n\n### Document Tools (3 tools)\n- `gemini_analyze_document` - Analyze PDFs, DOCX, TXT, etc.\n- `gemini_summarize_pdf` - Summarize PDF documents\n- `gemini_extract_tables` - Extract tables from documents\n\n### URL Tools (3 tools)\n- `gemini_analyze_url` - Analyze one or more URLs\n- `gemini_compare_urls` - Compare two URLs\n- `gemini_extract_from_url` - Extract specific data from a URL\n\n### Video Tools (2 tools)\n- `gemini_generate_video` - Generate videos using Veo\n- `gemini_check_video` - Check video generation status\n\n### YouTube Tools (2 tools)\n- `gemini_youtube` - Analyze YouTube videos\n- `gemini_youtube_summary` - Summarize YouTube videos\n\n### Voice Tools (3 tools)\n- `gemini_speak` - Convert text to speech\n- `gemini_dialogue` - Generate multi-voice dialogue audio\n- `gemini_list_voices` - List available voices\n\n### Research Tools (3 tools)\n- `gemini_deep_research` - Perform multi-step web research\n- `gemini_check_research` - Check research operation status\n- `gemini_research_followup` - Ask follow-up questions\n\n### Cache Tools (4 tools)\n- `gemini_create_cache` - Create content cache for repeated queries\n- `gemini_query_cache` - Query cached content\n- `gemini_list_caches` - List all active caches\n- `gemini_delete_cache` - Delete a cache\n\n### Structured Output Tools (2 tools)\n- `gemini_structured` - Get structured JSON output\n- `gemini_extract` - Extract structured data from text\n\n### Token Tools (1 tool)\n- `gemini_count_tokens` - Count tokens in content\n\n### Code Execution Tools (1 tool)\n- `gemini_run_code` - Execute Python code via Gemini\n\n**Total: 39 tools**\n\n## Installation\n\n### With uvx (Recommended)\n\n```bash\nuvx mcp-gemini-crunchtools\n```\n\n### With pip\n\n```bash\npip install mcp-gemini-crunchtools\n```\n\n### With Container\n\n```bash\n# Create a shared output directory (required before first run)\nmkdir -p ~/.local/share/mcp-uploads-downloads\n\npodman run -v ~/.local/share/mcp-uploads-downloads:/output:z \\\n    -e GEMINI_API_KEY=your_key \\\n    -e GEMINI_OUTPUT_DIR=/output \\\n    quay.io/crunchtools/mcp-gemini\n```\n\n> **SELinux note:** Use `:z` (lowercase, shared) instead of `:Z` (uppercase, private).\n> MCP servers run as long-lived stdio processes. With `:Z`, files copied into the\n> directory after container start won't have the container's private MCS label and\n> will be invisible inside the container. The `:z` flag sets a shared\n> `container_file_t` context that all containers and the host can read/write.\n>\n> **Tip:** Use the same shared directory (`~/.local/share/mcp-uploads-downloads/`)\n> across multiple MCP container servers (e.g., mcp-gemini and mcp-wordpress) so\n> generated images are immediately available for WordPress upload without copying.\n\n## Configuration\n\n### Creating a Google Gemini API Key\n\n1. **Navigate to Google AI Studio**\n   - Go to https://aistudio.google.com/apikey\n   - Sign in with your Google account\n\n2. **Create API Key**\n   - Click \"Get API key\" or \"Create API key\"\n   - Select a Google Cloud project or create a new one\n   - Click \"Create API key in new project\" (or select existing project)\n\n3. **Copy Your API Key**\n   - **IMPORTANT: Copy the API key immediately** - store it securely!\n   - The key starts with `AI...` (e.g., `AIzaSy...`)\n\n### Add to Claude Code\n\n```bash\nclaude mcp add mcp-gemini-crunchtools \\\n    --env GEMINI_API_KEY=your_api_key_here \\\n    -- uvx mcp-gemini-crunchtools\n```\n\nOr for the container version:\n\n```bash\n# Create a shared output directory (required before first run)\nmkdir -p ~/.local/share/mcp-uploads-downloads\n\nclaude mcp add mcp-gemini-crunchtools \\\n    --env GEMINI_API_KEY=your_api_key_here \\\n    --env GEMINI_OUTPUT_DIR=/output \\\n    -- podman run -i --rm \\\n        -v ~/.local/share/mcp-uploads-downloads:/output:z \\\n        -e GEMINI_API_KEY \\\n        -e GEMINI_OUTPUT_DIR=/output \\\n        quay.io/crunchtools/mcp-gemini\n```\n\n### Optional: Set Output Directory (non-container)\n\nFor generated images, audio, and videos when running without a container:\n\n```bash\nclaude mcp add mcp-gemini-crunchtools \\\n    --env GEMINI_API_KEY=your_api_key_here \\\n    --env GEMINI_OUTPUT_DIR=$HOME/.local/share/mcp-uploads-downloads \\\n    -- uvx mcp-gemini-crunchtools\n```\n\n## Usage Examples\n\n### Query with Google Search\n\n```\nUser: What are the latest developments in quantum computing?\nAssistant: [calls gemini_query with use_google_search=true]\n```\n\n### Generate an Image\n\n```\nUser: Generate a photorealistic image of a sunset over mountains\nAssistant: [calls gemini_generate_image with prompt and style]\n```\n\n### Analyze a PDF Document\n\n```\nUser: Analyze this research paper at /path/to/paper.pdf\nAssistant: [calls gemini_analyze_document with file_path]\n```\n\n### Summarize a YouTube Video\n\n```\nUser: Summarize this YouTube video: https://youtube.com/watch?v=...\nAssistant: [calls gemini_youtube_summary with url]\n```\n\n### Deep Research\n\n```\nUser: Research the environmental impact of electric vehicles\nAssistant: [calls gemini_deep_research then gemini_check_research]\n```\n\n### Code Analysis\n\n```\nUser: Analyze this Python code for security issues\nAssistant: [calls gemini_analyze_code with focus=\"security\"]\n```\n\n## Security\n\nThis server was designed with security as a primary concern. See [SECURITY.md](SECURITY.md) for:\n\n- Threat model and attack vectors\n- Defense in depth architecture\n- API key handling best practices\n- Input validation rules\n- Audit logging\n\n### Key Security Features\n\n1. **API Key Protection**\n   - Stored as SecretStr (never accidentally logged)\n   - Environment variable only (never in files or args)\n   - Sanitized from all error messages\n\n2. **Input Validation**\n   - Pydantic models for all inputs\n   - File path validation\n   - URL validation\n   - Strict format validation\n\n3. **API Hardening**\n   - Hardcoded API base URL (prevents SSRF)\n   - TLS certificate validation\n   - Request timeouts\n   - Response size limits\n\n4. **Automated CVE Scanning**\n   - GitHub Actions scan dependencies weekly\n   - Automatic PRs for security updates\n   - Dependabot alerts enabled\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/crunchtools/mcp-gemini.git\ncd mcp-gemini\nuv sync\n```\n\n### Run Tests\n\n```bash\nuv run pytest\n```\n\n### Lint and Type Check\n\n```bash\nuv run ruff check src tests\nuv run mypy src\n```\n\n### Build Container\n\n```bash\npodman build -t mcp-gemini .\n```\n\n## License\n\nAGPL-3.0-or-later\n\n## Contributing\n\nContributions welcome! Please read SECURITY.md before submitting security-related changes.\n\n## Links\n\n- [Google Gemini API Documentation](https://ai.google.dev/docs)\n- [Google AI Studio](https://aistudio.google.com/)\n- [FastMCP Documentation](https://gofastmcp.com/)\n- [MCP Specification](https://modelcontextprotocol.io/)\n- [crunchtools.com](https://crunchtools.com)\n\n<!-- mcp-name: io.github.crunchtools/gemini -->\n",
  "bytes": 9783,
  "sha": "2f6c9da2cdc0a3529d20b5af9cdc6168ecc9dcac729c265898a67c4a8890b263",
  "repo_slug": "crunchtools/mcp-gemini",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_crunchtools_gemini_08b800f0/readme"
}