MCP Gemini

MCP Gemini CrunchTools

面向 Google Gemini AI 的安全 MCP（Model Context Protocol）服务，支持文本、图像、视频、研究等功能。

概览

此 MCP 服务旨在实现：

• 默认安全 - 采用 STRIDE 威胁模型（参见 SECURITY.md）、Pydantic 输入验证，并将 API 密钥作为 SecretStr 保存，以防意外记录到日志中
• 无第三方服务 - 通过 stdio 在本地运行，API 密钥绝不会离开你的设备
• 跨平台 - 支持 Linux、macOS 和 Windows
• 自动更新 - GitHub Actions 会监控 CVE 并更新依赖项
• 容器化 - 可通过 quay.io/crunchtools/mcp-gemini 获取，基于 Hummingbird Python 基础镜像构建

命名约定

组件	名称
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 - 使用 Gemini 查询，可选启用 Google Search grounding
• 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 - 从文本中提取结构化数据

Token 工具（1 个工具）

• gemini_count_tokens - 计算内容中的 Token 数量

代码执行工具（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 密钥

   • 点击“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 Search 查询

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