MCP Gemini CrunchTools

Безопасный MCP-сервер (Model Context Protocol) для Google Gemini — текст, изображения, видео, исследования и многое другое.

Обзор

Этот MCP-сервер разработан с учётом следующих принципов:

• Безопасность по умолчанию — комплексное моделирование угроз, валидация входных данных и защита API-ключей

• Без сторонних сервисов — работает локально через stdio, ваш API-ключ никогда не покидает вашу машину

• Кроссплатформенность — работает на Linux, macOS и Windows

• Автоматические обновления — GitHub Actions отслеживают CVE и обновляют зависимости

• Контейнеризация — доступен в quay.io/crunchtools/mcp-gemini на базе образа Hummingbird Python

Related MCP server: Gemini Research MCP Server

Соглашение об именовании

Почему Hummingbird?

Контейнерный образ построен на базе Hummingbird Python из проекта Hummingbird, который обеспечивает:

• Минимальное количество CVE — образы Hummingbird содержат минимальный набор пакетов, что значительно снижает поверхность атаки по сравнению с универсальными образами

• Регулярные обновления — исправления безопасности применяются оперативно, количество CVE остаётся низким

• Оптимизация для Python — предварительно настроенное окружение Python с менеджером пакетов uv для быстрой и воспроизводимой сборки

• Готовность к продакшену — разработан для production-нагрузок с корректной обработкой сигналов и запуском от непривилегированного пользователя

Это означает, что ваш MCP-сервер работает в защищённом окружении с меньшим количеством уязвимостей, чем в типичных Python-контейнерах.

Возможности

Инструменты запросов (5 инструментов)

• gemini_query — запрос к Gemini с опциональным поиском Google

• gemini_brainstorm — генерация креативных идей по теме

• gemini_analyze_code — анализ кода на безопасность, производительность, ошибки

• gemini_analyze_text — анализ текста: тональность, стиль, содержание

• gemini_summarize — суммаризация контента в различных форматах

Генерация изображений (4 инструмента)

• gemini_generate_image — генерация изображений по текстовым запросам (нативный Gemini)

• gemini_generate_image_with_input — редактирование/изменение существующих изображений

• gemini_image_prompt — создание эффективных промптов для генерации изображений

• gemini_imagen_generate — генерация изображений с помощью моделей Google Imagen 4

Редактирование изображений (4 инструмента)

• gemini_start_image_edit — запуск многошаговой сессии редактирования изображения

• gemini_continue_image_edit — продолжение активной сессии редактирования

• gemini_end_image_edit — завершение сессии редактирования изображения

• gemini_list_image_sessions — список всех активных сессий редактирования

Анализ изображений (1 инструмент)

• gemini_analyze_image — анализ и описание локальных файлов изображений

Поисковые инструменты (1 инструмент)

• gemini_search — веб-поиск через Gemini с использованием Google Search Grounding

Инструменты для документов (3 инструмента)

• gemini_analyze_document — анализ PDF, DOCX, TXT и других форматов

• gemini_summarize_pdf — суммаризация PDF-документов

• gemini_extract_tables — извлечение таблиц из документов

Инструменты для URL (3 инструмента)

• gemini_analyze_url — анализ одного или нескольких URL

• gemini_compare_urls — сравнение двух URL

• gemini_extract_from_url — извлечение конкретных данных из URL

Видеоинструменты (2 инструмента)

• gemini_generate_video — генерация видео с помощью Veo

• gemini_check_video — проверка статуса генерации видео

Инструменты для YouTube (2 инструмента)

• gemini_youtube — анализ видео с YouTube

• gemini_youtube_summary — суммаризация видео с YouTube

Голосовые инструменты (3 инструмента)

• gemini_speak — преобразование текста в речь

• gemini_dialogue — генерация многоголосого аудио

• gemini_list_voices — список доступных голосов

Инструменты исследований (3 инструмента)

• gemini_deep_research — многошаговое веб-исследование

• gemini_check_research — проверка статуса исследования

• gemini_research_followup — уточняющие вопросы по исследованию

Инструменты кэширования (4 инструмента)

• gemini_create_cache — создание кэша контента для повторяющихся запросов

• gemini_query_cache — запрос к кэшированному контенту

• gemini_list_caches — список всех активных кэшей

• gemini_delete_cache — удаление кэша

Инструменты структурированного вывода (2 инструмента)

• gemini_structured — получение структурированного JSON-вывода

• gemini_extract — извлечение структурированных данных из текста

Инструменты подсчёта токенов (1 инструмент)

• gemini_count_tokens — подсчёт токенов в контенте

Инструменты выполнения кода (1 инструмент)

• gemini_run_code — выполнение Python-кода через Gemini

Всего инструментов: 39

Установка

С помощью uvx (рекомендуется)

uvx mcp-gemini-crunchtools

С помощью pip

pip install mcp-gemini-crunchtools

С помощью контейнера

# 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: используйте :z (строчная, общая) вместо :Z (заглавная, приватная). MCP-серверы работают как долгоживущие stdio-процессы. При использовании :Z файлы, скопированные в каталог после запуска контейнера, не будут иметь приватную метку MCS контейнера и будут невидимы внутри контейнера. Флаг :z устанавливает общий контекст container_file_t, который доступен на чтение и запись и контейнерам, и хосту.

Совет: используйте одну и ту же общую директорию (~/.local/share/mcp-uploads-downloads/) для нескольких MCP-контейнеров (например, mcp-gemini и mcp-wordpress), чтобы сгенерированные изображения были сразу доступны для загрузки в WordPress без копирования.

Настройка

Создание API-ключа Google Gemini

1. Перейдите в Google AI Studio

   • Откройте https://aistudio.google.com/apikey

   • Войдите в свой аккаунт Google

2. Создайте API-ключ

   • Нажмите «Get API key» или «Create API key»

   • Выберите проект Google Cloud или создайте новый

   • Нажмите «Create API key in new project» (или выберите существующий проект)

3. Скопируйте ваш API-ключ

   • ВАЖНО: скопируйте API-ключ сразу же — храните его в безопасном месте!

   • Ключ начинается с AI... (например, AIzaSy...)

Добавление в Claude Code

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

Или для версии с контейнером:

# 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

Необязательно: указание каталога вывода (без контейнера)

Для сгенерированных изображений, аудио и видео при запуске без контейнера:

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

Примеры использования

Запрос с поиском Google

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

Генерация изображения

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

Анализ PDF-документа

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

Суммаризация видео с YouTube

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

Глубокое исследование

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

Анализ кода

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

Безопасность

Этот сервер разработан с безопасностью как главным приоритетом. См. SECURITY.md для получения информации о:

• Модели угроз и векторах атак

• Многоуровневой архитектуре защиты

• Рекомендациях по безопасному обращению с API-ключами

• Правилах валидации входных данных

• Аудите логирования

Ключевые функции безопасности

1. Защита API-ключей

   • Хранение в виде SecretStr (никогда не попадают в логи случайно)

   • Только через переменные окружения (никогда в файлах или аргументах)

   • Очистка из всех сообщений об ошибках

2. Валидация входных данных

   • Pydantic-модели для всех входных данных

   • Валидация путей к файлам

   • Валидация URL

   • Строгая валидация форматов

3. Усиление безопасности API

   • Жёстко заданный базовый URL API (предотвращает SSRF)

   • Проверка TLS-сертификатов

   • Таймауты запросов

   • Лимиты размера ответов

4. Автоматическое сканирование CVE

   • GitHub Actions еженедельно сканируют зависимости

   • Автоматические PR для обновлений безопасности

   • Включены уведомления Dependabot

Разработка

Настройка окружения

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

Запуск тестов

uv run pytest

Линтинг и проверка типов

uv run ruff check src tests
uv run mypy src

Сборка контейнера

podman build -t mcp-gemini .

Лицензия

AGPL-3.0-or-later

Вклад в проект

Приветствуется! Пожалуйста, прочитайте SECURITY.md перед отправкой изменений, связанных с безопасностью.

Ссылки

• Документация Google Gemini API

• Google AI Studio

• Документация FastMCP

• Спецификация MCP

• crunchtools.com