gemini-mcp

gemini-mcp

用于 Google Gemini 媒体生成的 MCP 服务。通过 stdio 向 Claude 提供 13 种工具：列出可用模型、生成／编辑／组合图像、根据主提示词生成一组风格一致的图像、多轮图像优化（Interactions API）、视频生成（omni）、音乐生成（Lyria）、用于长时间生成的异步结果轮询，以及用于重复使用图像参考的 Files API 上传／列出／删除。默认将输出写入磁盘（并返回路径），也可以内联 base64 形式返回。基于 Gemini v1beta API（generativelanguage.googleapis.com），使用 Nano Banana / Nano Banana Pro（图像）、omni（视频）和 Lyria（音乐）模型系列。

由 AI（Claude Code）开发和维护。

环境变量

变量	必填	说明
GEMINI_API_KEY	是	你的 Google Gemini API 密钥（aistudio.google.com/apikey）
GEMINI_IMAGE_MODEL	否	覆盖默认图像模型（默认值：gemini-nano-banana-2.1）
GEMINI_OUTPUT_DIR	否	生成图像的默认目录（默认值：~/Downloads/gemini-mcp）。设置后，每次调用的 output_dir 必须位于此目录中。
GEMINI_INPUT_DIR	否	用于解析不带路径的输入图像文件名的目录（这样 images: ["foo.jpg"] 就能正常工作）
GEMINI_UPLOAD_DIR	否	将传输至 Gemini Files API 的本地文件（gemini_upload_file 的 path、video_path）限制在这些目录中——可指定一个或多个目录，以 : 分隔（Windows 上使用 ;）；允许使用 ~。超出范围的路径会在上传前被拒绝。未设置：不限制
GEMINI_REFERENCE_DIR	否	将本地图像参考图（读取并发送给 Gemini 的 images / master_images 路径——内联传输，或重复使用时通过 Files API 上传）限制在这些目录中——以 : 分隔（Windows 上使用 ;），允许使用 ~；GEMINI_OUTPUT_DIR 也始终允许使用，因此生成的图像可以重新作为输入。超出范围的路径（跟随符号链接后）会在读取前被拒绝。未设置：改为应用 GEMINI_UPLOAD_DIR。如果两者均未设置，则本地安装不限制参考图范围（服务器可读取的任何文件都可以发送），设置 MCP_DATA_DIR 时（托管环境）则限制在 $MCP_DATA_DIR/uploads 中
GEMINI_TIMEOUT_MS	否	上游请求超时时间（毫秒；默认值：60000，image_size: "4K" 时为 120000）；每个生成工具也支持单次调用的 timeout_ms
GEMINI_HEARTBEAT_MS	否	生成期间发送进度通知的间隔（毫秒；默认值：10000；0 表示禁用）——避免那些在收到进度通知后会重置超时计时的 MCP 主机因生成时间过长而超时
GEMINI_CHAIN_RETRY_MS	否	链式调用返回 404 时，等待 interactions-store 延迟的最长时间（默认值：120000；0 表示禁用重试）

确认

向 Google 发送本地文件（images / master_images / video_path 输入，或 gemini_upload_file 的 path）以及每项删除操作，都需要先确认。能够显示确认提示的客户端（Claude Code）会收到实际提示，除非 MCP_CONFIRM_ELICITATION=off。其他情况下，首次调用不会执行任何操作，而是返回预览（解析后的本地路径及其 MIME 类型和大小，或要删除的方法/路径）以及一个 confirmToken；只有使用相同参数和该令牌再次调用，操作才会继续。令牌只能使用一次，会过期，并且绑定到确切的参数——两次调用之间若提示词有变或文件被替换，操作都会被拒绝。纯文本提示词、URL、files/ 引用和 base64 输入不受此限制。

变量	默认值
MCP_CONFIRM_MODE	ask-user	对于无法显示确认提示的客户端（claude.ai、Claude Desktop），写入操作的处理方式。ask-user：分两步执行——首次调用不执行任何操作，而是返回预览和令牌；模型必须先在聊天中获得你的批准，然后才能使用该令牌再次调用。auto：同样分两步执行，但模型查看预览后即可使用令牌。refuse：此类客户端上的写入操作会被拒绝。能够显示提示的客户端（Claude Code）始终会收到实际提示，除非 MCP_CONFIRM_ELICITATION=off。无法识别的值会按 refuse 处理。
MCP_CONFIRM_ELICITATION	on	off 表示绝不显示确认提示，因此所有客户端都会采用 MCP_CONFIRM_MODE 路径。对于声称支持提示、但从不显示提示的客户端（受限调用会挂起——opencode 2.0.x），请设置此项。其他任何值都会保持 on，并在 stderr 上显示警告。
MCP_CONFIRM_TTL_SECONDS	600	令牌的有效时长。
MCP_CONFIRM_SECRET	每个进程随机生成	签名密钥；仅当令牌必须在服务重启后仍然有效时才设置。

长时间生成与客户端超时

4K / Pro 模型的生成可能会超过 MCP 主机自身的 tools/call 超时（错误 -32001）。 服务会发送 notifications/progress 心跳，以便会在收到进度通知时重置超时的主机继续等待。如果主机仍然放弃等待，服务端的生成通常仍会完成：图像会写入输出目录，gemini_interact 还会写入一个 <image>.json 旁置文件，记录 interaction_id；而 continue_last: true 会恢复丢失响应所属的交互。

链式调用出现 404 时

携带 previous_interaction_id 的请求返回 404，并不能证明链已过期。目前实际观察到的唯一 404 响应正文是通用提示——"Requested entity was not found."——从未指出哪个实体未找到。未知或已重命名的模型 ID，以及已过期的 Files API files/… URI（TTL 约为 48 小时），都会返回完全相同的内容。因此，服务器不再断言它无法确认的原因：上游文本会原样呈现，而 gemini_interact 会进行实验，以查明究竟是哪种情况。

很多时候，ID 并非不存在，而只是尚未可见。交互存储采用最终一致性，新创建的 ID 可能返回 404，但几分钟后同一个 ID 就能正常解析；较重的轮次（4K、Pro、thinking_level: high）最容易遇到这种情况，而这些轮次也正是你最希望能接着调用的。因此，链式调用出现 404 时，会采用指数退避重试，最长 120s（GEMINI_CHAIN_RETRY_MS），之后才会判定失败。404 不会生成任何内容，也不会计费，所以等待只耗费时间。

重试时间用尽后，工具会查找该 ID 的 sidecar，重新附上它生成的图像，并在不带链的情况下重新发起请求：

• 重新发起请求成功 → 问题确实出在链上，你仍会得到图像，并收到 chain_recovered: { expired_interaction_id, reanchored_on } 报告。返回 404 的尝试不会生成任何内容，因此这只需支付你手动重新锚定时原本就要支付的一次生成费用。
• 重新发起请求也返回 404 → 问题并非由交互 ID 引起。你会收到明确说明和上游文本，并被提示检查模型 ID 和任何 files/… URI，而不是被误导去追查一个一直正常的交互。
• 没有 sidecar 与失效的 ID 匹配 → 返回原始错误，而不是猜测。基于错误的图像重新锚定会在不知不觉中破坏编辑结果。

另外，continue_last 不再会随服务器进程结束而失效：如果内存中没有 ID，它会从输出目录中最新的 <image>.json sidecar 恢复，并报告 continued_from_sidecar: true。这种情况从来都不是链过期——交互一直在上游保持有效，只是我们丢失了对其 ID 的记录。

对于无法控制超时的宿主（例如 Claude Desktop，其固定约 30s 的超时上限会忽略进度），以下两种保护机制可确保重新发起请求安全且没有必要：

• async: true 会立即返回 job_id，而不是图像，因此调用不会超时；使用该 job_id 轮询 gemini_get_result，直到状态变为 done。
• idempotency_key 可确保重复调用具有幂等性——使用相同键重试时，会返回已记录的结果（reused: true），而不是再次对生成收费。（即使不使用键，两个内容相同且同时进行中的调用也会自动去重。）

工具

工具	描述
gemini_list_models	列出可用的 Gemini 图像模型和当前默认模型
gemini_image_generate	根据文本提示词生成图像
gemini_image_edit	根据文本指令进行单次编辑或多图合成（如需连续多次编辑，请使用 gemini_interact）
gemini_image_set	生成一张主图以及 N 张以其为参考、风格一致的图像
gemini_interact	迭代优化的首选工具：通过 Interactions API 进行多轮生成／编辑——通过 previous_interaction_id（或 continue_last: true）传入返回的 interaction_id 以继续交互
gemini_video_generate	通过 Gemini omni 模型生成短视频（文本→视频、图像→视频、两张静帧插值、edit 或 extend）；resolution 360p/720p/1080p/4k 是影响成本的因素；结果以 MP4 格式写入磁盘
gemini_music_generate	通过 Lyria 模型根据文本提示词生成音乐——lyria-3-clip-preview（30s，默认）、lyria-3.5（完整长度，含人声）或 lyria-3-pro-preview；单轮生成；结果以 MP3 格式写入磁盘
gemini_get_result	根据 job_id 获取以 async: true 启动的异步生成任务（状态从 running 变为 done 时返回结果）。可让长时间生成任务不受主机 tools/call 超时影响
gemini_token_usage	查看截至目前本次会话的令牌用量和估算的 USD 成本。在工作流前后各调用一次，然后相减即可计算该工作流的开销。根据日期对应的费率表，按每次调用所用模型计价（GEMINI_RATE_CARD 可覆盖费率表）；由于没有可读取账户余额的端点，因此这是计算开销的方式
gemini_upload_file	将图像（或视频／音频）上传到 Gemini Files API 一次——来源可以是 url、data_base64 或本地 path——并获取可重复使用的 files/<id> 引用
gemini_list_files	列出当前使用此 API 密钥上传的文件及其 MIME 类型和过期时间
gemini_delete_file	在已上传文件约 48h 后过期前将其删除（需先确认——参见确认）
gemini_sign_media	（仅限托管部署） 根据生成媒体的 r2_key 创建新的签名 URL——链接过期后仍可重新获取
gemini_view_media	（仅限托管部署） 根据 r2_key 将生成的图像作为内嵌图像块返回，以便模型在优化前实际查看生成结果
gemini_get_upload_url	（仅限托管部署） 创建一个短时有效的签名 PUT URL，使 shell 无需身份验证标头即可上传参考图像；PUT 请求会返回一个 r2_key，可用于 images_r2_keys、gemini_save_character 或 gemini_upload_file
gemini_save_character / gemini_list_characters / gemini_delete_character	（仅限托管部署） 按账户持久保存的角色库：以名称保存参考图像和描述，然后在生成工具中传入 characters: ["name"]。不会过期
gemini_save_style / gemini_list_styles / gemini_delete_style	（仅限托管部署） 按账户持久保存的风格预设：可重复使用的提示词片段（可选附带参考图像），在生成工具中传入 style: "name" 即可应用。不会过期

生成工具还共享三项吞吐量／延迟控制选项：async: true（立即返回 job_id）、max_wait_ms（等待至指定时长后返回 job_id——快速结果会直接返回，慢速批次则不会触发主机超时），以及 idempotency_key（重试时返回已记录的结果，而不会重复计费）。在托管部署中，包含多张图像的 gemini_image_set 结果还会附带一个 bundle_url——这是包含该集合中所有图像的 zip 文件的单个签名 URL。与所有托管链接一样，其有效期最长为 24h（受主机 blob 存储上限限制）；过期后可通过 gemini_sign_media 重新生成。（如果图像集合过大，无法安全地在内存中打包成 zip，则会跳过压缩包，并通过 bundle_skipped 说明；每张图像的链接不受影响。）

查看你的图片（托管环境）

在托管部署中没有文件系统，因此生成的图片必须以你可以打开的形式返回。确实如此：每个结果都包含一个 URL，无需配置。

{
  "images": ["https://mcp.nullnet.app/b/<account>/gemini/gen/2026-07-29/ab12cd34-a-cat.png?exp=…&sig=…"],
  "media":  [{ "url": "https://…", "r2_key": "gen/2026-07-29/ab12cd34-a-cat.png",
               "expires_at": "2026-07-31T12:00:00.000Z",
               "curl_hint": "curl -sS -o a-cat.png \"https://…\"" }]
}

这些链接无需身份验证标头——签名包含在 URL 中——因此可在浏览器、curl 和聊天消息中使用。它们最多 24h 后过期——主机的 blob 存储不接受更长的签名——链接指向的对象则会按主机的保留策略清理。r2_key 是这段有效期内可持久使用的句柄：

• gemini_sign_media（仅限托管部署）通过 r2_key 生成新的签名 URL，因此链接过期后无需重新生成图片，也无需再次付费。
• 每张图片旁都会存储交互 ID，因此托管部署恢复丢失的对话轮次时，方式与本地部署相同：重启后 continue_last: true 仍然有效，链式调用遇到 404 时会重新锚定到该交互生成的图片，而 gemini_list_recent_media 会显示每个已存储对象的提示词、模型和交互 ID，而不是只显示一堆键。
• gemini_view_media（仅限托管部署）通过 r2_key 内联返回图片本身。模型无法查看链接，因此没有此工具时，生成 → 优化的循环就只能盲目进行。它是单独的一次调用，而不是在每个结果中都附带图片字节：只有在实际查看的对话轮次中才会产生图片令牌费用。
• 使用 r2_key 调用 gemini_upload_file，可将此服务生成的媒体转换为 Files API 引用（服务使用自己的密钥读取媒体，你无需生成签名），因此生成的图片只需一次成本低廉的调用，就能成为下一次生成的参考图片。
• 幂等重放（idempotency_key）会在返回记录的结果前重新生成其中的 URL，因此重复使用结果时不会携带失效链接。

为何这很重要： MCP 的内联图片内容块（inline: true）对助手可见，但许多聊天客户端不会将其渲染给用户，而且助手无法从自身上下文中提取图片字节，以便保存到其他位置。生成可能成功计费，但结果却不可见。URL 是可移植的解决方案；inline 仍然可用，但它不再是接收媒体的唯一方式。

字节如何提供

主机会存储每个生成的对象，并通过带有签名且会过期的 URL 提供对象——https://<host>/b/<account>/gemini/<key>?exp=&sig=。无需设置，也无需身份验证标头：链接中的签名就是授权凭证，因此 curl 和浏览器都能使用。

身份验证使用带签名且会过期的 URL，而不是未列出的密钥。 随机密钥可能更简单，但它们永不过期，也无法撤销：任何曾经记录或转发过该链接的人，都能永远使用它。签名将访问权限限定为单个对象，并设定截止时间；轮换主机的签名密钥（MCP_BLOB_SIGNING_KEY，由 mcp-host 与 MCP_BLOB_BASE_URL 一同注入，本服务不会选择这两者）会立即使所有尚未过期的链接失效。代价是链接较长，无法手动缩短。

助手转发结果时

向用户展示 URL。如果你的沙盒可以通过网络访问主机，获取 URL 并将字节作为文件附上，效果最好；否则直接提供链接即可。不同客户端对 ![](url) Markdown 内联内容的渲染方式各不相同——裸 URL 是安全的形式；如果你确定客户端支持渲染，Markdown 链接也是合理的增强方式。

保留期限

保留期限由宿主决定，而非此服务的设置。在 mcp-host 上，blob 存储会按自己的计划清理生成的媒体（gen/）和签名上传内容（up/）（参见 mcp-host docs/BLOB-STORE.md；默认 30 天）；角色／风格库（lib/）则标记为免于清理，因此已保存的条目永不过期。每个签名链接的有效期都限制在存储的 24 小时上限内，因此不会超过存储实际认可的期限；只要对象存在，gemini_sign_media 就会为其重新签发链接。此服务读取的相关变量由宿主注入：MCP_BLOB_BASE_URL 和 MCP_BLOB_SIGNING_KEY。

提示词也会被存储。 在托管部署中，每个生成的对象旁边都会有一条小型 JSON 记录，其中保存提示词（前 500 个字符）、模型和交互 ID——gemini_list_recent_media 显示的就是这些内容，也正是这些信息能让丢失的对话轮次得以恢复。记录与对象一起保存和清理，因此保留时长与对象相同，不会更久。在本地，gemini_interact 会在输出目录中为每张图片写入一个 <image>.json 旁路文件（包含模型、交互 ID、选项以及模型回复的任何文本，但不包含提示词）；这些文件由你决定保留或删除，不会自行过期。如果你的提示词描述了真实人物，请注意它们会在你的存储桶中保留整个保留期限。

发送参考图片而不消耗上下文

所有接受参考图片的工具——gemini_image_generate、gemini_image_edit、gemini_image_set、gemini_interact，以及 gemini_video_generate（参考静帧）和 gemini_music_generate——都支持四种传递方式。其中只有一种会消耗模型上下文：

参数	字节的传输方式	上下文开销
images_url（master_images_url）	服务下载 https URL	无
images_file_uris（master_images_file_uris）	已上传的 files/<id> 引用	无
images_r2_keys（master_images_r2_keys）	服务读取其自有存储（仅限托管部署）	无
images	从本地磁盘读取（仅限 stdio 构建）	无
characters / style	按名称附加已保存的库条目（仅限托管部署）	无
images_base64	通过工具调用 JSON 传递	每张 JPEG 约 14k 个 token

images_base64 是万不得已时的最后选择。每张普通照片大约会消耗 14k 个 token；如果读取文件时发生截断，生成的内容就会被静默破坏——载荷看起来仍像 base64，因此最终表现为生成结果异常，而不是报错。优先使用其他方式。

images_url — 由服务获取图片

{ "prompt": "make it look like winter", "images_url": ["https://example.com/photo.jpg"] }

获取范围仅限公开的 https:// URL——私有、回环和链路本地地址都会被拒绝（会解析 IPv6 字面量，因此 [::ffff:7f00:1] 会被识别为回环地址）；每次重定向都会重新验证，且每一跳都有超时限制。响应的 Content-Type 必须为 image/*，大小上限为 15MB；该上限通过流式传输期间强制执行，而非依赖 Content-Length。发生故障时会指出有问题的 URL。超过 6MB 的内容会上传到 Files API，并通过 uri 引用，而不是直接内嵌，因为 generateContent 对整个请求的大小限制约为 20MB。

images_file_uris — 上传一次，多次引用

// 1. upload
{ "tool": "gemini_upload_file", "url": "https://example.com/photo.jpg" }
// → { "file_uri": "files/abc123", "mime_type": "image/jpeg", "expires": "..." }

// 2. reference it, as many times as you like
{ "prompt": "make it winter",  "images_file_uris": ["files/abc123"] }
{ "prompt": "make it sunrise", "images_file_uris": ["files/abc123"] }

上传内容会保留 约 48 小时；之后引用将无法解析（会返回通用的 404，参见上文的连续 404 部分）。gemini_image_set 只会获取或解析此类引用一次，然后将其传递给主调用和每个场景调用。

在 stdio 构建中，如果本地 images 路径在一个会话中被引用多次，系统会自动将其上传到 Files API（以路径 + mtime + 大小作为键），这样重复编辑同一张照片时就不必再次发送字节。编辑文件会使缓存的上传内容失效。

签名上传 URL——完全无需令牌（托管版）

这是拥有 shell 的 Agent 的预期使用方式：磁盘文件 → curl → r2_key → 工具调用， 图片不会进入对话。gemini_get_upload_url 会生成一个短时有效（约 10 分钟）的签名 PUT URL，shell 无需任何身份验证标头即可上传——URL 中的签名就是授权凭证，与下载链接的工作方式相同。

# 1. tool call: gemini_get_upload_url { filename: "photo.jpg", content_type: "image/jpeg" }
#    → { upload_url, r2_key, expires_at, curl_hint }

# 2. shell:
curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "$UPLOAD_URL"
# → { "r2_key": "up/<tenant>/2026-07-31/ab12cd34-photo.jpg", "size_bytes": 812345, ... }

签名涵盖一个限定租户范围的对象键、声明的内容类型和有效期；上传大小上限为 15MB，读取数据流时会强制执行。只接受栅格图像类型（jpeg/png/webp/gif/avif/heic/heif/bmp/tiff）——有意拒绝 SVG，因为 SVG 是可执行脚本的文档，而 /media 会从服务器自身的源提供内容。返回的 r2_key 有三种用途：直接作为任何生成工具的 images_r2_keys（服务器读取自己的存储桶——对话中不会包含图像字节）、通过 gemini_save_character 永久保存，或作为 gemini_upload_file({ r2_key }) 的 Files API 引用（约 48 小时有效）。上传文件本身遵循主机的 Blob 存储保留计划（up/ 前缀）。

角色与风格库（托管版）

可按账户保存反复使用的主体与风格，一次保存，永不过期（库中的 lib/ 对象不受保留策略限制，因此主机清理时会跳过它们）：

// once:
{ "tool": "gemini_save_character", "name": "finn",
  "description": "6-year-old boy, curly red hair", "image_r2_key": "up/…/photo.jpg" }
{ "tool": "gemini_save_style", "name": "bold-cartoon-sports",
  "prompt_fragment": "bold cartoon style, thick outlines, saturated colors" }

// afterwards, on any generation:
{ "tool": "gemini_image_set",
  "master_prompt": "Finn on a soccer field",
  "scenes": ["kicking the ball", "celebrating a goal"],
  "characters": ["finn"], "style": "bold-cartoon-sports" }

指定角色名称会附加其已保存的参考图像，并将描述融入提示词；指定风格名称会追加其片段（如果有参考图像，也会一并附加）。gemini_image_set 会将角色参考图像传递给主调用和每个场景调用，从而确保整组图像中的主体保持一致。

快速入门

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

完整用法文档请参阅 SKILL.md。