遗传- mcp

为谷歌双子座媒体生成的MCP服务器. 向克洛德展示13个工具 : 列出可用的模型,生成/编辑/编译图像,从主快多回合图像改进(Interactions API)生成一套一致的图像, 视频 世代, 音乐 生成(Lyria),一个针对长世代的同源结果民调,以及用于可再使用的图像引用的文件 API上传/列表/删除. 输出默认情况下会被写入磁盘( path return),或者作为碱基64返回入行. 建于双子座v1beta API上(generativelanguage.googleapis.com)使用"纳诺香蕉"(Nano Banana Pro (images)","OMNI"(video)"和"Lyria"(音乐)模范家庭.

由AI(Claude Code)开发和维护.

环境变量

确认

发送 本地文件 转到 Google ( images 编号 : master_images 编号 : video_path 输入,或 gemini_upload_file是因为 path和每个 删除 先请求确认 客户端可以 显示确认提示( Claude Code) 获得真实提示, 除非 MCP_CONFIRM_ELICITATION=off。 。 。 . 在别的地方,第一个电话是 无并返回预览(已解析的本地路径及其MIME类型和大小,或 方法/路径被删除)加a confirmToken;只有重复的呼唤,同样的论点和 那个象征性的收益。 符号是单用、过期的,并且与确切的论点——a 已更改的提示或两个调用之间的互换文件被拒绝 。 纯文本提示, URL, files/ 参考文献和基数64没有门.

长辈和客户超时

4K / 亲模代能跑过 MCP 主机本身 tools/call 超时( 错误) -32001) (中文(简体) ). 服务器发送 notifications/progress 心跳使主机重新设定超时 进步等待它出来。 如果主机仍然放弃, 服务器侧生成通常会完成 无论如何: 图像写入输出目录, gemini_interact 也写着 <image>.json 侧车记录 interaction_id,以及 continue_last: true 恢复 共享丢失的响应属于.

当连锁电话404

404应请求携带 previous_interaction_id 实值 没有 证明链已过期 。 这个 仅观测到404具活体是通用的—— "Requested entity was not found." - 从来没有名字 哪个 实体。 未知或更名 型号编号,以及过期的文件 API files/… 乌里 (~48h TTL),返回完全相同的东西. 这样服务器就不再声称不能 确定:上游文本是逐字浮出 gemini_interact 运行一个实验到 找出是哪个.

通常,身份证明完全没有丢失——它只是不是 可见 还没有。 互动商店是 最终一致,一个刚创建的id可以404 而同样的id解决 细分钟 后;重转(4K,正, thinking_level: high最能击出它 这正是你最想要的 链从。 所以一个被锁链的404 重试的指数 备份最多 120岁 (单位:千美元)GEMINI_CHAIN_RETRY_MS在宣布任何破损之前。 这个 404没有产生什么,也没有计费,所以等待成本只有时间.

预算用完后,工具检查了ID的侧车, 重新接上它的形象 并重新发出请求 无 链条 :

• 重发成功 - 锁链真的是问题, 反正你得到你的形象, 报告为 chain_recovered: { expired_interaction_id, reanchored_on }404的尝试 所以这要花一代人的钱 来做手动的重新定位.
• 再发行404 互动 ID 从来不是原因。 你被告知, 和上游文字,并指代模型 id 和任何 files/… 里 而不是现在 被派去追寻一个一直很好的互动.
• 没有侧行车匹配死亡的ID - 最初的错误,而不是猜测。 重新纠缠 错误的图片会悄悄地腐蚀编辑.

分开, continue_last 不再随服务器进程而死:没有内存编号 从最新 <image>.json 输出目录和报告中的侧车 continued_from_sidecar: true案件从来就不是一个过期的链条——相互作用 在上游一直活着 只有我们对它的记忆消失了.

对于不能被驯服而超时的主机(例如克洛德桌面,一个被忽略的固定的~30s盖) 两名警卫负责安全、不必要地重新发放:

• async: true 返回 a job_id 而不是影像,所以电话不能 完全超时;民意调查 gemini_get_result 与 job_id 直到它变成 done。 。 。 .
• idempotency_key 使重复调用“同键”重试返回 记录结果(reused: true)取而代之,取而代之. (即使没有钥匙, 两个相同的飞行中电话自动调用。 )

工具

生成工具还共享三个吞吐量/纬度控制: async: true ( 返回 a job_id 立即, max_wait_ms (等待预算,然后把 job_id ——成绩保持快 带内,慢批次从不绊倒主机超时),并 idempotency_key (重试返回 记录结果,而不是重新计票)。 在托管的部署中,a gemini_image_set 结果 多个图像还带有 bundle_url ——一个签名的 URL,用于对每个图像进行拉链 设定。 与每个主机链接一样,它最多活到24小时(主机的blob-store天花板); gemini_sign_media 重点一个过期的。 (设定太高,不能 在记忆中安全地拉链 跳过捆绑 并说通过 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,在聊天留言中。 最多24小时后就过期了 东道主的blob商店拒绝 更长的签名——以及后面的物体被覆盖在主机的保存时间表上. 这个 r2_key 是窗口的持久控件 :

• gemini_sign_media (只托管部署) 薄荷从一个 r2_key, (中文(简体) ), 因此,一个过期的链接永远不会迫使你重新生成——并重新支付——图像.
• 交互 ID 存储在每个图像旁边,所以一个主机部署 恢复一个丢失 改变当地人的方式: continue_last: true 在重启后幸存下来,链式404是 重新关注互动产生的形象 gemini_list_recent_media 显示 每个存储对象的即时,模型和交互id,而不是一串密钥的墙.
• gemini_view_media (仅主机部署)从内线返回图像本身 r2_key连结不是模型可以看的东西,所以没有这个生成 ~ 精细 循环运行失明。 这是一个单独的呼叫,而不是每个结果的字节:你支付图像 只在你实际看的转弯处有指示牌.
• gemini_upload_file 与 r2_key 将此服务器生成的媒体转换成文件 API 参考(服务器用自己的密钥读回来——没有签名让你做薄荷),所以 一个生成的图像可以在一个便宜的呼叫中成为下一代的参考图像.
• 重复播放(idempotency_key)在记录结果中重命名 URL 所以再利用的结果 永远不会有死链.

为什么这很重要: MCP的内置图像内容块(inline: true)可见 助理人员 但很多聊天客户端从未将它们提供给用户,而助理不能 从自己的上下文中取出字节以保存到其他地方. 一代人会付帐 成功和隐形。 URL是可移植的答案; inline 仍然可用,但 这不再是接受媒体的唯一办法.

字节是如何送达的

主机存储每个生成的对象, 并按签名服务到到期 URL —— (中文) https://<host>/b/<account>/gemini/<key>?exp=&sig=。没有设置,也没有认证 标题:链接中的签名是授权,所以 curl 和浏览器 两者都行.

Auth 是已签名的, 过期的 URL 而不是未列出的密钥 . 随机键将 简而言之,但不会过期,也不会撤销 链接将永远运作。 签字范围包括进入一个有最后期限的物体,以及 旋转主机签名密钥( r)MCP_BLOB_SIGNING_KEY时,mcp-host会与 MCP_BLOB_BASE_URL; 此服务器从不选择) 使每个未完成的链接无效 一次 一次吗 权衡的是,联系很长,不能靠手缩短.

助理转发结果

显示用户的 URL 。 如果您的沙盒有网络向主机进发, 获取它 并附加字节作为文件给出最优的结果;否则会呈现链接本身. 给定客户端是否使 ![](url) 标记下内线因客户端而异——一个空的 URL 是 安全的形式, 和标记下的联系 是合理增强 在你知道它会.

保留

保留是主机的,不是这个服务器的设置. 在mcp -host, 斑点商店花花 生成的介质 (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 侧式车(型号、互动代号、选项和 模型在输出目录中每个图像旁边用任何文本——而不是提示本身——回答; 这些文件是属于你的 保存或删除, 永远不会过期 自己。 狦 提示中描述的是真实的人 记住他们坐在你的水桶里.

不燃烧上下文而发送参考图像

每一个有参考图像的工具—— gemini_image_generate, (中文(简体) ), gemini_image_edit, (中文(简体) ), gemini_image_set, (中文(简体) ), gemini_interact附加时 gemini_video_generate (参考保留)和 gemini_music_generate - 接受它们四种方式。 其中只有一个成本模型背景:

images_base64 是最后手段的倒计时。 每张小照片大约要花费14克, 它默默地腐烂了,只要文件读出它,它就被截断了 有效载荷看起来仍然像基座64,所以故障表面是一个坏一代而不是一个 错误。 偏取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所取所相相相相相相相相相.

images_url ——服务器获取

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

获取仅限于公开 https:// URL — 私有、回回和链接本地主机 拒绝( IPv6 字节被解析, 所以) [::ffff:7f00:1] 以回转方式抓取,每个方向 hop被重新验证,每个hop都会被限定为超时. 对策必须是 Content-Type: image/* 并封顶于 15MB (英语),在流出而非信任时执行 从 Content-Length。失败会命名违法的 URL 。 超过6MB的任何东西都会上传到 文件 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 被引用的路径 一次以上的会议 实值 自动上传到文件 API( 键于路径 + mtime + 大小), 因此重复编辑 同一相片停止重接字节。 编辑文件将缓存上传无效 .

已签名的上传 URL —— 完全没有符号( 托管)

这是有外壳的代理商的预定路径: 磁盘文件 ~ 卷曲 ~ r2_key - 工具呼叫, 图像从不进入对话. gemini_get_upload_url 薄荷薄荷短命 (~10分钟)签名 点 URL,且 shell 上传了 0 认证头 — 签名在 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,或者作为 ~48h 文件 API 的参考 gemini_upload_file({ r2_key })。 。 。 . 上传自己遵循主机的 blob- store 保留时间表(up/ 前缀).

字符样式库( 托管) (S)

经常性主体和样式可以保存一次,每个账户,用 无过期 (图书馆的) lib/ 对象被写入保留豁免,所以主机的prune跳过它们:

// 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"
      }
    }
  }
}

见 SKILLL.MD (英语) 供充分使用的文件.