MCP Gemini CrunchTools

Un servidor MCP (Protocolo de Contexto de Modelo) seguro para Google Gemini AI: texto, imágenes, vídeo, investigación y más.

Descripción general

Este servidor MCP está diseñado para ser:

• Seguro por defecto: modelado integral de amenazas, validación de entradas y protección de claves de API

• Sin servicios de terceros: se ejecuta localmente a través de stdio, tu clave de API nunca sale de tu máquina

• Multiplataforma: funciona en Linux, macOS y Windows

• Actualizado automáticamente: los flujos de trabajo de GitHub Actions supervisan CVEs y actualizan dependencias

• Contenerizado: disponible en quay.io/crunchtools/mcp-gemini construido sobre la imagen base Hummingbird Python

Related MCP server: Gemini Research MCP Server

Convención de nomenclatura

¿Por qué Hummingbird?

La imagen de contenedor está construida sobre la imagen base Hummingbird Python de Project Hummingbird, que proporciona:

• Exposición mínima a CVEs: las imágenes Hummingbird se construyen con un conjunto mínimo de paquetes, lo que reduce drásticamente la superficie de ataque en comparación con las imágenes de propósito general

• Actualizaciones periódicas: los parches de seguridad se aplican con prontitud, manteniendo bajos los recuentos de CVEs

• Optimizada para Python: entorno de Python preconfigurado con el gestor de paquetes uv para compilaciones rápidas y reproducibles

• Lista para producción: diseñada para cargas de trabajo de producción con manejo de señales adecuado y valores predeterminados de usuario no root

Esto significa que tu servidor MCP se ejecuta en un entorno endurecido con menos vulnerabilidades que las imágenes típicas de contenedores de Python.

Características

Herramientas de consulta (5 herramientas)

• gemini_query - Consulta a Gemini con opción de fundamento de Búsqueda de Google

• gemini_brainstorm - Genera ideas creativas sobre un tema

• gemini_analyze_code - Analiza código en busca de seguridad, rendimiento y errores

• gemini_analyze_text - Analiza texto en busca de sentimiento, tono y contenido

• gemini_summarize - Resume contenido en varios formatos

Generación de imágenes (4 herramientas)

• gemini_generate_image - Genera imágenes a partir de indicaciones de texto (Gemini nativo)

• gemini_generate_image_with_input - Edita/modifica imágenes existentes

• gemini_image_prompt - Elabora indicaciones efectivas de generación de imágenes

• gemini_imagen_generate - Genera imágenes usando los modelos Google Imagen 4

Edición de imágenes (4 herramientas)

• gemini_start_image_edit - Inicia una sesión de edición de imágenes de varios turnos

• gemini_continue_image_edit - Continúa editando en una sesión activa

• gemini_end_image_edit - Finaliza una sesión de edición de imágenes

• gemini_list_image_sessions - Lista todas las sesiones de edición activas

Análisis de imágenes (1 herramienta)

• gemini_analyze_image - Analiza y describe archivos de imagen locales

Herramientas de búsqueda (1 herramienta)

• gemini_search - Búsqueda web usando Gemini con fundamento de Búsqueda de Google

Herramientas de documentos (3 herramientas)

• gemini_analyze_document - Analiza PDF, DOCX, TXT, etc.

• gemini_summarize_pdf - Resume documentos PDF

• gemini_extract_tables - Extrae tablas de documentos

Herramientas de URL (3 herramientas)

• gemini_analyze_url - Analiza una o más URL

• gemini_compare_urls - Compara dos URL

• gemini_extract_from_url - Extrae datos específicos de una URL

Herramientas de vídeo (2 herramientas)

• gemini_generate_video - Genera vídeos usando Veo

• gemini_check_video - Comprueba el estado de generación de vídeos

Herramientas de YouTube (2 herramientas)

• gemini_youtube - Analiza vídeos de YouTube

• gemini_youtube_summary - Resume vídeos de YouTube

Herramientas de voz (3 herramientas)

• gemini_speak - Convierte texto a voz

• gemini_dialogue - Genera audio de diálogo con varias voces

• gemini_list_voices - Lista las voces disponibles

Herramientas de investigación (3 herramientas)

• gemini_deep_research - Realiza investigación web de varios pasos

• gemini_check_research - Comprueba el estado de la operación de investigación

• gemini_research_followup - Haz preguntas de seguimiento

Herramientas de caché (4 herramientas)

• gemini_create_cache - Crea caché de contenido para consultas repetidas

• gemini_query_cache - Consulta contenido en caché

• gemini_list_caches - Lista todas las cachés activas

• gemini_delete_cache - Elimina una caché

Herramientas de salida estructurada (2 herramientas)

• gemini_structured - Obtén salida JSON estructurada

• gemini_extract - Extrae datos estructurados de texto

Herramientas de tokens (1 herramienta)

• gemini_count_tokens - Cuenta los tokens en el contenido

Herramientas de ejecución de código (1 herramienta)

• gemini_run_code - Ejecuta código Python a través de Gemini

Total: 39 herramientas

Instalación

Con uvx (Recomendado)

uvx mcp-gemini-crunchtools

Con pip

pip install mcp-gemini-crunchtools

Con contenedor

# 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

Nota sobre SELinux: Usa :z (minúscula, compartido) en lugar de :Z (mayúscula, privado). Los servidores MCP se ejecutan como procesos stdio de larga duración. Con :Z, los archivos copiados al directorio después del inicio del contenedor no tendrán la etiqueta MCS privada del contenedor y serán invisibles dentro del contenedor. La bandera :z establece un contexto compartido container_file_t que todos los contenedores y el host pueden leer/escribir.

Consejo: Usa el mismo directorio compartido (~/.local/share/mcp-uploads-downloads/) en múltiples servidores MCP de contenedores (p. ej., mcp-gemini y mcp-wordpress) para que las imágenes generadas estén disponibles inmediatamente para la carga en WordPress sin copiarlas.

Configuración

Creación de una clave de API de Google Gemini

1. Navega a Google AI Studio

   • Ve a https://aistudio.google.com/apikey

   • Inicia sesión con tu cuenta de Google

2. Crea una clave de API

   • Haz clic en "Obtener clave de API" o "Crear clave de API"

   • Selecciona un proyecto de Google Cloud o crea uno nuevo

   • Haz clic en "Crear clave de API en un proyecto nuevo" (o selecciona un proyecto existente)

3. Copia tu clave de API

   • IMPORTANTE: Copia la clave de API inmediatamente - ¡guárdala de forma segura!

   • La clave comienza con AI... (p. ej., AIzaSy...)

Añadir a Claude Code

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

O para la versión de contenedor:

# 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

Opcional: Establecer el directorio de salida (sin contenedor)

Para imágenes, audio y vídeos generados cuando se ejecuta sin contenedor:

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

Ejemplos de uso

Consulta con Búsqueda de Google

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

Generar una imagen

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

Analizar un documento PDF

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

Resumir un vídeo de YouTube

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

Investigación profunda

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

Análisis de código

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

Seguridad

Este servidor fue diseñado con la seguridad como prioridad principal. Consulta SECURITY.md para:

• Modelo de amenazas y vectores de ataque

• Arquitectura de defensa en profundidad

• Buenas prácticas de manejo de claves de API

• Reglas de validación de entradas

• Registro de auditoría

Características clave de seguridad

1. Protección de claves de API

   • Almacenada como SecretStr (nunca se registra accidentalmente)

   • Solo variable de entorno (nunca en archivos o argumentos)

   • Saneada de todos los mensajes de error

2. Validación de entradas

   • Modelos Pydantic para todas las entradas

   • Validación de rutas de archivo

   • Validación de URL

   • Validación estricta de formato

3. Endurecimiento de API

   • URL base de API codificada (evita SSRF)

   • Validación de certificados TLS

   • Tiempos de espera de solicitud

   • Límites de tamaño de respuesta

4. Escaneo automatizado de CVEs

   • Los flujos de trabajo de GitHub Actions escanean dependencias semanalmente

   • PR automáticas para actualizaciones de seguridad

   • Alertas de Dependabot habilitadas

Desarrollo

Configuración

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

Ejecutar pruebas

uv run pytest

Lint y verificación de tipos

uv run ruff check src tests
uv run mypy src

Compilar contenedor

podman build -t mcp-gemini .

Licencia

AGPL-3.0-o posterior

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lee SECURITY.md antes de enviar cambios relacionados con la seguridad.

Enlaces

• Documentación de la API de Google Gemini

• Google AI Studio

• Documentación de FastMCP

• Especificación MCP

• crunchtools.com