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

命名约定

为什么选择 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

   • 前往 https://aistudio.google.com/apikey

   • 使用您的 Google 账户登录

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。

链接

• Google Gemini API 文档

• Google AI Studio

• FastMCP 文档

• MCP 规范

• crunchtools.com