gemini

Gemini MCP - 在 Claude 中使用 Google Gemini 图像生成、视频和搜索依据

近一年来，我一直在 Claude Desktop 配置中运行这个 Gemini MCP 服务。它是少数几个我会一直保持启用的服务之一。这不是因为 Gemini 可以取代 Claude（它做不到），而是因为搜索依据、图像生成、SVG 图表和视频恰好是 Gemini 擅长的功能，而在 Claude 中将它们作为工具使用，胜过在浏览器标签页之间来回切换。

这里有 14 个工具，围绕大家实际想用的模型构建：用于图像的 Nano Banana Pro（gemini-3-pro-image）和 Nano Banana 2，支持音画同步的视频生成模型 Veo 3.1，用于聊天的 Gemini 4 Argon，以及用于深度研究的 Gemini 3.1 Pro；后两者都支持 Google Search 搜索依据。借助 MCP Apps，所有内容都会直接在 Claude Desktop 中预览，而不是只给出一个你还得自己打开的文件路径。

只需一条 npx 命令，就这么简单。

刚接触这个项目？完整用户指南介绍了每个工具、免费层级的注意事项，以及遇到问题时的处理方法。

---

快速导航

可以生成什么 | 快速开始 | 功能介绍 | 图像输出 | 配置 | 工具 | 模型 | 要求

---

它能做什么

以下内容均是在我写下这些文字的当天午后，直接由本仓库中的工具生成，未经修改。提示词写在说明文字中，你可以自行判断。

结合搜索结果生成图像。 一次 generate_image 调用，并将 use_search=true。Gemini 查询了英国气象局当周的实际预报，然后据此绘制图像。日期和气温都是真实的（嗯，至少对天气预报来说算真实）。

提示词：“一张精致的编辑风格信息图海报：本周伦敦天气。使用搜索结果中的未来 5 天真实预报数据……”——gemini-3-pro-image，16:9，2K。

文字拼写准确无误。 这是 Nano Banana Pro 能做到、而前几代图像模型做不到的事情。这里的每个标签都由模型直接生成。

提示词：“一张简洁、杂志级别的信息图，标题为 MCP 工具调用的工作原理，包含四个编号步骤……”——gemini-3-pro-image。

先生成，再编辑。 左图使用 generate_image 生成。右图则是对该文件调用 edit_image，并附上一句说明：将赛道换成白天的蒙扎赛道，把轮廓光换成窗光，并把踏板改成红色。座舱相同，摄像机角度相同。

generate_image	edit_image

用 Veo 3.1 将图像转成视频。 将上方的夜间座舱图像作为 firstFrameImage 传给 generate_video。生成的视频时长 8 秒、分辨率 1080p，并带有生成的音频（引擎声、轮胎嘶鸣声）——下方 GIF 为适配 GitHub 而压缩处理，且没有声音；实际文件是标准 MP4。

真正可用的 SVG。 不是图表的图片，而是真正的矢量标记语言，可直接放进网页、手动编辑或提交到代码仓库。以下两张图都是工具写入磁盘的原始 .svg 文件。

generate_svg style=technical	generate_svg style=data-viz

用一段文字生成落地页。 使用 generate_landing_page，提供简要说明、公司名称和品牌色。生成的是独立 HTML，包含内联 CSS，首屏中的小图表是动画 SVG。截图来自在 Chrome 中打开生成文件的效果，未做其他改动。

还有速度更快的版本。 Nano Banana 2（gemini-3.1-flash-image），适合追求产量而非 4K 的场景。这次大约花了 10 秒。

---

两分钟快速上手

步骤 1：获取 Gemini API 密钥

前往 Google AI Studio 并创建一个密钥。

关于免费套餐，需要说明一点：默认设置会使用付费模型。Google 的定价页面为 Gemini 3 Flash Preview 提供免费套餐，但旗舰模型仅限付费使用——gemini-4-argon 是 gemini_chat 和 generate_landing_page 的默认模型，而 gemini-3.1-pro-preview 是 gemini_deep_research（综合）和 analyze_image 的默认模型。使用免费密钥时，这些调用会失败，除非你将它们指定为免费模型：设置 GEMINI_DEFAULT_MODEL=gemini-3-flash-preview（适用于聊天和着陆页）、相应设置 GEMINI_DEEP_RESEARCH_MODEL 和 GEMINI_IMAGE_ANALYSIS_MODEL，或在每次调用时传入 model。generate_svg 已默认使用 gemini-3-flash-preview。使用其他模型前，请先查看定价页面——Google 会调整这些套餐。

步骤 2：添加到 Claude Desktop 配置

配置文件位置：

• Windows：C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["@houtini/gemini-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

步骤 3：重启 Claude Desktop

就这样。工具会自动显示。首次运行时，npx 会拉取软件包，因此无需单独安装。

改用本地构建

用于开发，或者如果你不想依赖 npx：

git clone https://github.com/houtini-ai/gemini-mcp
cd gemini-mcp
npm install --include=dev
npm run build

然后将配置指向本地构建：

{
  "mcpServers": {
    "gemini": {
      "command": "node",
      "args": ["C:/path/to/gemini-mcp/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Code（CLI）

Claude Code 不会读取 claude_desktop_config.json。请改用 claude mcp add：

claude mcp add -e GEMINI_API_KEY=your-api-key-here -s user gemini -- npx -y @houtini/gemini-mcp

指定用于存放图像和视频的输出目录：

claude mcp add \
  -e GEMINI_API_KEY=your-api-key-here \
  -e GEMINI_IMAGE_OUTPUT_DIR=/path/to/output \
  -s user \
  gemini -- npx -y @houtini/gemini-mcp

使用 claude mcp get gemini 检查——你应看到 Status: Connected。

---

功能介绍

使用 Google Search grounding 聊天

Use gemini:gemini_chat to ask: "What changed in the MCP spec in the last month?"

默认启用 grounding。Gemini 会先搜索 Google 再作答，因此你获得的是本月的信息，而不是基于训练数据截止时间的猜测；来源也会以 Markdown 链接的形式返回。对于希望纯粹进行推理的问题（例如“解释这段代码”），请设置 grounding: false。

除非另有指定，否则会使用 gemini-4-argon（Gemini 4 Argon）。如果你更看重速度而非深度，可传入 model: "gemini-3.8-flash"；若要使用上一代旗舰模型，则传入 model: "gemini-3.1-pro-preview"。thinking_level 适用于 Gemini 3.x 和 4 模型：处理难题时设为 high，想要快速响应时设为 low。

深度研究

Use gemini:gemini_deep_research with:
  research_question="What are the current approaches to AI agent memory management?"
  max_iterations=5

先进行多轮基于搜索的研究，再将结果汇总为一份报告。研究轮次使用低思考级别的 gemini-3.8-flash（用于收集事实，而非推理），最后的综合环节则使用高思考级别的 gemini-3.1-pro-preview。默认进行两轮研究，再加上一次综合，全程约需两到三分钟。

这种模型分工比听起来更重要。早期版本会用 Pro 和完整思考级别完成所有工作，而对于宽泛的问题，单轮研究本身就可能超过 Claude Desktop 的四分钟超时限制。在 Claude Desktop 中，将 max_iterations 保持在 2 或 3；在 IDE 或 Agent 框架中，设为 5 到 7 能明显提升综合效果。如果想为每轮研究设定方向，focus_areas 可接受一个数组。

使用搜索 grounding 生成图像

Use gemini:generate_image with:
  prompt="Stock price chart showing Apple (AAPL) closing prices for the last 5 trading days"
  use_search=true
  aspectRatio="16:9"

默认模型是 gemini-3-pro-image，它现在已结束预览阶段，更名为 Nano Banana Pro。它可以渲染清晰可读的文字、生成 4K 图像，也是唯一支持对话式编辑的模型。gemini-3.1-flash-image（Nano Banana 2）速度更快——质量相差不大，耗时和成本却低得多。如果要生成数百张图像，也有 Lite 版本可用。

启用 use_search=true 后，Gemini 会先查询信息再绘图。天气、价格、体育赛事结果等依赖数据的图像都能可靠生成。完整分辨率的文件始终会写入磁盘；内联预览会缩小以适应 MCP 传输上限，但原图不会受到影响。

使用 Veo 3.1 生成视频

Use gemini:generate_video with:
  prompt="A close-up shot of a futuristic coffee machine brewing a glowing blue espresso, steam rising dramatically. Cinematic lighting."
  resolution="1080p"
  durationSeconds=8

Google 的 Veo 3.1。可生成时长为 4 至 8 秒、分辨率最高达 4K 且原生支持音画同步的片段。生成过程在 Google 端异步进行，需要两到五分钟；工具会持续轮询，直到生成完成，因此你无需等待。

值得了解的选项：

• aspectRatio - 16:9 横向，或 9:16 纵向
• generateAudio - 默认开启；可生成与提示词相符的对白和音效
• firstFrameImage - 从静帧开始制作动画（上方的驾驶舱片段就是这样制作的）
• referenceImages - 最多三张，用于保持角色或风格一致
• sampleCount - 一次调用最多生成四种变体
• seed - 确保多次运行的输出具有确定性
• generateThumbnail - 如果你的 PATH 中有 ffmpeg，则可提取一帧
• model - 如果想要更省钱、更快的生成速度，可选用 veo-3.1-lite-generate-preview

生成 SVG

这是大家最容易低估的一项功能。输出不是图表的图片，而是 SVG 标记本身——放入代码库、幻灯片或网页中即可使用，缩放时不会产生任何栅格伪影。

Use gemini:generate_svg with:
  prompt="Architecture diagram showing a microservices system with API gateway, three services, and a shared database"
  style="technical"
  width=1000
  height=600

四种风格：

风格	最适合
technical	架构图、流程图、系统图
artistic	插图、装饰图形、图标
minimal	简洁的数据可视化、简单图表
data-viz	图表、仪表板、信息图

返回的是真正的 SVG 代码。你可以编辑、制作动画、嵌入或提交代码，无需导出，也无需使用 Figma。

除非传入 model，否则会使用 gemini-3-flash-preview——它速度快，能轻松处理 SVG 标记，并提供免费层级。如果你使用付费密钥，需要生成更复杂的图表，可传入 model: "gemini-3.1-pro-preview"。

图像编辑与分析

对话式编辑。 Nano Banana Pro 会在多轮对话间保留上下文。将上一次调用返回的 thought signature 传回，它就会记住正在处理的内容：

Use gemini:edit_image with:
  prompt="Change the colour scheme to blue and green"
  images=[{filePath: "C:/output/gemini-123.png", thoughtSignature: "fromPreviousCall"}]

分析，两种工具各司其职：

• describe_image - 使用 gemini-3.8-flash 快速生成通用描述
• analyze_image - 使用 gemini-3.1-pro-preview 进行结构化提取和深入推理

本地文件：

Use gemini:load_image_from_path with filePath="C:/screenshots/error.png"

或者直接将 filePath 传入任意图像工具的 images 数组，由服务自行读取文件——这样就能完全绕过 MCP 传输限制。

媒体分辨率控制

在任务不需要细节时，可将 token 用量最多降低 75%：

级别	Token 数	节省比例	最适合
MEDIA_RESOLUTION_LOW	280	75%	简单任务、批量操作
MEDIA_RESOLUTION_MEDIUM	560	50%	PDF 和文档（OCR 在此级别已达到饱和）
MEDIA_RESOLUTION_HIGH	1120	默认	详细分析
MEDIA_RESOLUTION_ULTRA_HIGH	2000+	仅限单张图像	最高细节

对于 PDF OCR，MEDIUM 的文本提取效果与 HIGH 完全相同，但 token 用量只有一半。我还没遇到过例外。

生成落地页

Use gemini:generate_landing_page with:
  brief="A SaaS tool that helps developers monitor API latency"
  companyName="PingWatch"
  primaryColour="#6366F1"
  style="startup"
  sections=["hero", "features", "pricing", "cta"]

生成一个独立的 HTML 文件：CSS 内联、使用原生 JS，无外部依赖。样式包括 minimal、bold、corporate 和 startup。上方画廊中的 PingWatch 页面正是通过这次调用生成的。

专业图表设计体系

gemini_prompt_assistant 内置了九种图表设计体系，你可以按名称指定：

体系	灵感来源	最适合
storytelling	Cole Nussbaumer Knaflic	高管演示
financial	Financial Times	新闻编辑部风格的新闻报道——FT 粉色、衬线标题
terminal	Bloomberg / fintech	高密度暗色模式，搭配霓虹色
modernist	W.E.B. Du Bois	大胆的几何色块、强烈对比
professional	IBM Carbon / Tailwind	企业仪表板
editorial	FiveThirtyEight / Economist	数据新闻
scientific	Nature / Science	严谨的学术风格
minimal	Edward Tufte	最大化数据墨水比
dark	Observable	现代暗色模式

帮助系统

Use gemini:gemini_help with topic="overview"

无需离开 Claude 即可查看完整文档。主题：overview、image_generation、image_editing、image_analysis、chat、deep_research、grounding、media_resolution、models、all。

---

图像输出与存储

默认情况下，图像会以嵌入式预览的形式返回，直接在 Claude 中显示；完整尺寸的文件则会写入软件包所在目录。如果希望所有文件都保存到合适的位置，可以设置 GEMINI_IMAGE_OUTPUT_DIR：

"env": {
  "GEMINI_API_KEY": "your-api-key-here",
  "GEMINI_IMAGE_OUTPUT_DIR": "C:/Users/username/Pictures/gemini-output"
}

每张图像对应两个文件：

文件	说明
完整分辨率	立即保存到磁盘，未经修改
预览图	调整尺寸后的 JPEG，用于嵌入式传输，大小符合上限

Gemini 返回的图像大小为 2 到 5 MB。调整尺寸时，会先测量每个响应中的非图像数据开销，再计算剩余的二进制数据预算，然后依次将预览图缩小至 800、600、400、300、200px，直至低于 1 MB 的 MCP 传输限制。完整图像始终保存在磁盘上。

Claude Desktop 中的内嵌查看器

图像、SVG、视频和落地页结果都会在 MCP App 查看器中打开，支持缩放，并提供保存路径和复制按钮。如果你使用的是 Claude Desktop，且在较旧版本中查看器一直停留在“Waiting for image...”，那是因为 Claude Desktop 丢弃了查看器读取的结构化数据（ext-apps#696）。从 2.7.0 起，查看器会自行从服务端获取数据，因此无论如何都能渲染。

---

配置参考

变量	必填	默认值	说明
GEMINI_API_KEY	是	-	从 AI Studio 获取的 Google AI API 密钥
GEMINI_DEFAULT_MODEL	否	gemini-4-argon	gemini_chat 和 generate_landing_page 使用的模型
GEMINI_DEEP_RESEARCH_MODEL	否	gemini-3.1-pro-preview	gemini_deep_research 使用的综合模型
GEMINI_DEEP_RESEARCH_SEARCH_MODEL	否	gemini-3.8-flash	gemini_deep_research 中有依据的搜索轮次所用模型
GEMINI_IMAGE_ANALYSIS_MODEL	否	gemini-3.1-pro-preview	analyze_image 使用的模型
GEMINI_IMAGE_DESCRIBE_MODEL	否	gemini-3.8-flash	describe_image 使用的模型
GEMINI_IMAGE_GENERATION_MODEL	否	gemini-3-pro-image	generate_image 和 edit_image 使用的模型
GEMINI_DEFAULT_GROUNDING	否	true	设置为 false，默认关闭 Google Search grounding
GEMINI_IMAGE_OUTPUT_DIR	否	-	生成的图像和视频的保存位置
GEMINI_ALLOW_EXPERIMENTAL	否	false	在自动发现中包含实验版和预览版模型
GEMINI_REQUEST_TIMEOUT_MS	否	240000	聊天和分析请求的单次超时时间，单位为毫秒
GEMINI_MCP_RETRY_ATTEMPTS	否	3	每次 Gemini API 请求的总尝试次数。会通过退避重试临时网络故障（fetch failed、ECONNRESET、代理或 VPN 连接中断）。设为 1 可禁用重试
GEMINI_MCP_LOG_FILE	否	false	将日志写入 ~/.gemini-mcp/logs/
DEBUG_MCP	否	false	将工具调用的调试日志写入 stderr

工具参考

工具	描述
gemini_chat	与 Gemini 4 Argon 聊天。默认启用 Google Search grounding。支持 thinking_level
gemini_deep_research	在 Flash 上执行有依据的搜索轮次，并由 3.1 Pro 综合生成报告。默认 2 轮
gemini_list_models	实时列出你的 API 密钥可访问的模型
gemini_help	无需离开 Claude 即可查看每个工具的文档
gemini_prompt_assistant	提供图像生成方面的专家指导，涵盖九种图表设计系统
generate_image	生成图像，可选择启用搜索 grounding。完整分辨率版本保存到磁盘
edit_image	使用自然语言指令编辑图像。通过 thought signatures 保持多轮编辑的连贯性
describe_image	使用 Gemini 3.8 Flash 快速描述图像
analyze_image	使用 Gemini 3.1 Pro 进行结构化提取与分析
load_image_from_path	读取本地图像文件，并返回供任何图像工具使用的 base64
generate_video	使用 Veo 3.1 生成视频：时长 4 到 8 秒，最高 4K，带原生音频
generate_svg	生成可用于生产环境的 SVG：图表、插图、图标、数据可视化
generate_landing_page	生成独立的 HTML 落地页，内含 CSS 和 JS
gemini_viewer_payload	内部工具。内嵌查看器使用它获取显示数据；你不会调用它

---

模型参考

根据 2026 年 9 月 22 日的实时模型 API 核对。gemini_list_models 会告诉你今天的密钥可以访问哪些模型。

模型	使用位置	说明
gemini-4-argon	gemini_chat、generate_landing_page	默认模型。Gemini 4 Argon——当前旗舰模型。仅限付费使用——没有免费套餐
gemini-3.1-pro-preview	gemini_deep_research（综合）、analyze_image	这两项功能的默认模型。推理能力强，仅限付费使用——没有免费套餐
gemini-3.8-flash	describe_image、gemini_deep_research（搜索阶段）	默认模型。截至 2026 年 9 月，Google 的正式发布版主力模型；需要速度时，也是 gemini_chat 的不错选择
gemini-3-flash-preview	generate_svg	默认模型。有免费套餐（Google 定价页面，2026 年 9 月 24 日）
gemini-3.7-flash、3.6、3.5、3.5-flash-lite、3.1-flash-lite	任意文本工具	较早发布的正式版 Flash 模型，均可使用
gemini-3-pro-image	generate_image、edit_image	默认模型。Nano Banana Pro，正式发布版。支持 4K、生成真实文本和对话式编辑
gemini-3.1-flash-image	generate_image、edit_image	Nano Banana 2，正式发布版。画质接近 Pro，速度和价格则与 Flash 相当
gemini-3.1-flash-lite-image	generate_image	Nano Banana 2 Lite。速度最快、价格最低
gemini-3-pro-image-preview、nano-banana-pro-preview、gemini-2.5-flash-image	图像工具	较旧的 ID，仍可使用，以便现有配置继续正常工作
veo-3.1-generate-preview	generate_video	默认模型。电影级效果、原生音频，最高支持 4K
veo-3.1-lite-generate-preview	generate_video	使用相同 API，价格更低、速度更快

为何采用这些默认模型。 我对此反复权衡过。Gemini 3.8 Flash 已正式发布，版本也更新，但 3.1 Pro 仍是 Google 所称的推理能力最强的模型，而推理正是 gemini_chat 和深度研究的核心需求——所以这两项仍默认使用 Pro，而更轻量的 describe_image 任务则使用 Flash。图像方面，Nano Banana Pro 已退出预览阶段，并保持画质领先，因此设为默认模型；如果你愿意牺牲一点画质来换取更快的速度，可以使用 Nano Banana 2。Gemini 更新的 Omni 视频模型使用不同的 API，因此目前尚未接入。

Gemini 3 说明： 所有 3.x 模型的温度都强制设为 1.0（这是 Google 的要求，较低的值会导致循环）。thinking_level 适用于 gemini_chat。

令牌预算： max_tokens 默认为各模型实时模型 API 报告的完整输出上限（当前 Gemini 3 文本模型为 65,536；1M 指的是输入上下文）。这是上限，而非实际消耗，因此未用到的额度不会产生费用。低于 4,096 的值会被忽略，因为 Gemini 3 的思考过程会在你看到任何输出前耗尽少量预算，表现得就像超时一样；高于模型实际限制的值则会被截断至该限制。

---

要求

• Node.js 20.19+
• 从 Google AI Studio 获取的 Gemini API 密钥
• ffmpeg（可选，用于生成视频缩略图）

许可证

Apache-2.0