Skip to main content
Glama

MCP Gemini CrunchTools

一个用于 Google Gemini AI 的安全 MCP(模型上下文协议)服务器——支持文本、图像、视频、研究等。

概述

该 MCP 服务器设计目标:

  • 默认安全 - 全面的威胁建模、输入验证和 API 密钥保护

  • 无第三方服务 - 通过 stdio 在本地运行,您的 API 密钥不会离开您的机器

  • 跨平台 - 支持 Linux、macOS 和 Windows

  • 自动更新 - GitHub Actions 监控 CVE 并更新依赖

  • 容器化 - 提供于 quay.io/crunchtools/mcp-gemini,基于 Hummingbird Python 基础镜像构建

Related MCP server: Gemini Research MCP Server

命名约定

组件

名称

GitHub 仓库

crunchtools/mcp-gemini

容器

quay.io/crunchtools/mcp-gemini

Python 包 (PyPI)

mcp-gemini-crunchtools

CLI 命令

mcp-gemini-crunchtools

模块导入

mcp_gemini_crunchtools

为什么选择 Hummingbird?

容器镜像基于 Project Hummingbird 的 Hummingbird Python 基础镜像 构建,提供:

  • 最小的 CVE 暴露 - Hummingbird 镜像以最小软件包集构建,与通用镜像相比大幅减少攻击面

  • 定期更新 - 及时应用安全补丁,保持较低的 CVE 数量

  • 为 Python 优化 - 预配置的 Python 环境,使用 uv 包管理器实现快速、可复现的构建

  • 生产就绪 - 专为生产工作负载设计,具有适当的信号处理和非 root 用户默认值

这意味着您的 MCP 服务器在加固的环境中运行,比典型的 Python 容器镜像具有更少的漏洞。

功能

查询工具(5 个工具)

  • gemini_query - 使用可选的 Google 搜索接地查询 Gemini

  • 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 搜索接地进行网络搜索

文档工具(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 - 通过 Gemini 执行 Python 代码

总计: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 上下文。

提示: 在多个 MCP 容器服务器(例如 mcp-gemini 和 mcp-wordpress)之间使用 相同的共享目录(~/.local/share/mcp-uploads-downloads/),这样生成的图像无需 复制即可立即可用于 WordPress 上传。

配置

创建 Google Gemini API 密钥

  1. 导航到 Google AI Studio

  2. 创建 API 密钥

    • 点击“获取 API 密钥”或“创建 API 密钥”

    • 选择 Google Cloud 项目或创建新项目

    • 点击“在新项目中创建 API 密钥”(或选择现有项目)

  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 加固

    • 硬编码 API 基础 URL(防止 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

Lint 和类型检查

uv run ruff check src tests
uv run mypy src

构建容器

podman build -t mcp-gemini .

许可证

AGPL-3.0-or-later

贡献

欢迎贡献!在提交与安全相关的更改之前,请阅读 SECURITY.md。

链接

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