我一开始真没觉得 Claude Code 需要会画画。装它进终端，纯粹是想让它帮我重构代码、跑测试、写 commit message。直到有一次我顺手问了句“给这篇博客配个封面图”，它憋了半天给我输出了一段 ASCII 字符拼的“封面”，那一瞬间我才反应过来：AI 编程助手和 AI 图像生成模型，原本被两个完全不同的窗口隔开了。左边是终端里噼里啪啦的代码补全，右边是网页上排了半天 prompt 的图片生成器，两边明明都是同一类东西，却天然地“各玩各的”。
后来我试了一下把 Nano Banana MCP 接进 Claude Code，这个割裂感算是彻底消失了。在终端里敲一行字，既能让它改代码，也能让它直接产出一张图、再基于这张图做局部修改，全程不离开命令行。这篇文章就记录我完整的接入过程、模型链路拆解、真实跑通的三个图像任务，以及我在这个过程中踩过的、大概率你也会踩的一堆坑。
1. 这个组合到底解决了什么问题：从“只在聊天框里出图”到“在终端里出图”
先分别说清楚这两个角色。Claude Code 是 Anthropic 官方推出的终端编程代理，你可以在终端里用自然语言指挥它读写文件、执行命令、搜索代码库、跑测试，本质上是一个住在命令行里的 AI Agent。Nano Banana 则是 Google Gemini 2.5 Flash Image 模型的社区昵称，这个模型在图像编辑上做得相当夸张，尤其是“保持主体一致性”的局部编辑，比如给同一只猫换不同场景、给同一件商品换背景，物体本身不会变形走样，这是传统扩散模型一直很难解决的事。
MCP 在这里扮演的角色，相当于 USB-C 接口。MCP 的全称是 Model Context Protocol，是 Anthropic 在 2024 年底推出来的一套标准化协议，专门用来让 AI 应用和外部工具做双向通信。Claude Code 天生支持 MCP，意味着你只要按协议接上某个 MCP 服务器，就能让 Claude Code 凭空获得一种新能力。Nano Banana MCP 服务器，就是把 Gemini 2.5 Flash Image 的图像生成与编辑能力包装成一个个标准工具，注册给 Claude Code 之后，模型就能在对话过程中自主决定“该调图像工具了”。
那为什么不直接用网页版？我的答案是：网页版的产出和整个工程流程是断裂的。你在网页上生成一张产品图，还得下载、重命名、拖进项目目录，再手写一段引用路径。而在终端里用 Claude Code 调 Nano Banana，模型可以直接读取你本地文件，生成结果落地到项目目录，再把路径写进 README、博客草稿或者代码注释里。整条链路是可以自动化的，这才是它对开发者最有吸引力的地方。
这套组合特别适合三类人。第一类是内容创作者，经常要给文章配封面、给视频做缩略图，但又不愿意在浏览器和编辑器之间来回切换；第二类是开发者，想在 CI/CD、文档生成、资源处理脚本里直接内嵌图像生成能力；第三类是纯粹的管理员玩家，就想在终端里用一套标准工作流，体验“一句话出图、一句话改图”的顺畅感。如果你只是偶尔生成一张图且完全不碰命令行，那网页版体验更好，没必要折腾 MCP。
在我的实测里，真正值钱的不是“生成一张图”这个动作，而是“图能进入工程上下文”这一点。比如我让它基于项目里某张截图生成一张风格统一的海报，它可以读文件、生成图、把图保存到 assets 目录、再顺手把图表写进说明文档，一次对话完成全流程。这个闭环，网页版给不了。
2. 安装与接入：Claude Code 里注册 Nano Banana 工具的完整过程
安装这关看似简单，但每一步都有讲究。我先给出一份可以直接照着抄的清单，再解释每一步为什么这么写。
2.1 准备环境：Node.js 版本和终端选择
Claude Code 本体是一个 npm 包，所以首要依赖是 Node.js 运行时。我建议装 Node.js 18 或更高版本，npm 会一并装好。安装完在终端验证一下版本：
node -v npm -v终端方面，macOS 上我推荐 iTerm2，Windows 上建议直接上 Windows Terminal，Linux 用户用系统自带的或 Tabby 这类现代终端都行。为什么强调中终端工具？因为稍后你要在终端里预览图片，iTerm2 的 imgcat 插件、Windows Terminal 的六国图片渲染能力，体验都比老掉牙的默认终端好得多。
2.2 安装 Claude Code
官方给出的安装命令是一个非常典型的全局 npm 装法：
npm install -g @anthropic-ai/claude-code装完后执行claude --version能看到版本号，就算成功。第一次运行claude会引导你登录账号、选择订阅计划，走完初始化流程后，你会进入一个 REPL 式交互环境，可以直接开始对话。
如果系统提示claude: command not found，那大概率是 npm 全局 bin 目录没进 PATH。macOS/Linux 上查看路径用npm bin -g，把结果加进 shell 配置文件即可。Windows 上一般会自动处理，遇到问题重新安装一次 Node.js 的 LTS 版本就好。
2.3 获取 Nano Banana 的访问凭证并安装 MCP 服务器
Nano Banana 底层走的是 Gemini 模型 API，所以需要一个能访问该服务的 API Key。这个 Key 的获取渠道以服务商官方指引为准，拿到后先导出到环境变量里测试一下：
export NANO_BANANA_API_KEY="你的API Key"验证这个 Key 能不能用，最简单的办法是直接请求一次官方 API 文档里的最小样例，也可以跳过这一步直接装 MCP 服务器，因为配置错误通常会在第一次调用时暴露出来。
MCP 服务器部分，社区里已经有几个开源实现，名字通常就叫nano-banana-mcp，用 npm 或 Python 打包的都有。我用的是 npm 版本，安装方式很简单：
npm install -g nano-banana-mcp你也可以不全局安装，而是在注册时用npx -y nano-banana-mcp临时拉取，这样每次运行时都会自动使用最新版本，缺点是首次启动会慢几秒。我个人的习惯是装成全局包，执行路径更可控，调试问题时也更容易定位。
2.4 在 Claude Code 里注册 MCP 服务器
注册操作是纯粹的配置动作。Claude Code 提供了一条交互式命令，直接在终端会话里执行：
claude mcp add nano-banana --env NANO_BANANA_API_KEY=你的API Key -- npx -y nano-banana-mcp注册完成后，用claude mcp list检查服务器状态，能看到 nano-banana 对应的 command 和 env 信息，就说明已经登记在册了。
如果想在某个项目内生效，不想全局污染，可以在项目根目录写一个.mcp.json：
{ "mcpServers": { "nano-banana": { "command": "npx", "args": ["-y", "nano-banana-mcp"], "env": { "NANO_BANANA_API_KEY": "你的API Key" } } } }注意：
.mcp.json里的命令会被 Claude Code 以项目工作目录为基准来解析。如果工具内部会按相对路径保存图片，图片最终会落在项目目录下，这一点后面排查路径问题时非常关键。
2.5 验证工具是否真正可调用
配置完成并不代表一切就绪。我建议进入 Claude Code 后直接问它：
列出你当前可用的 MCP 工具，并说明每个工具的作用正常情况下，它会把你注册的 nano-banana 工具和对应的函数签名列出来，包括生成图片用的 generate_image、编辑图片用的 edit_image 这类接口。如果它说“未找到 MCP 服务器”，多半是配置里的命令路径没找对，或者环境变量没传进去，回到上一步逐项排查即可。
3. 模型链路拆解：从一句 prompt 到一张本地图片，中间发生了什么
很多朋友第一次跑通 MCP 之后，会觉得“哇，好神奇”，但对背后发生了什么一头雾水。我建议花三分钟搞懂这个链路，因为后面排错全靠它。
3.1 一次工具调用的完整生命周期
当你在 Claude Code 里输入“帮我生成一张封面图”时，链路大致分为四步：
- 步骤一：Claude Code 的 Agent 循环把用户指令拆解，判断这属于图像生成任务，于是从已注册的工具列表里选中 nano-banana 的 generate_image。
- 步骤二：Claude Code 以 MCP 的协议格式发送一次函数调用请求，JSON-RPC 格式的消息里包含工具名称和参数，比如 prompt、size、aspect_ratio。
- 步骤三：MCP 服务器进程收到请求，把参数转成对应的模型 API 调用，将生成的图片保存到本地路径，再以结构化结果（通常是 JSON）返回给 Claude Code，内容包括图片路径、尺寸、token 消耗等。
- 步骤四：Claude Code 拿到返回结果，把这段信息作为新的上下文继续推理，最后面向用户总结，比如“图片已生成，保存在 assets/cover.png”。
整个过程看起来像 Claude 在“画图”，实际上 Claude 只负责调度和转述，真正动手画图的是 Nano Banana 模型。MCP 的价值在于把两个模型的能力做了标准的桥接，让 Claude 能够以函数调用方式，把用户的自然语言意图“翻译”成 Nano Banana 能理解的指令。
这一点直接解释了为什么你可以在终端里让 Claude “读图”。它并不是真的能看到图片的每一个像素，而是通过 MCP 返回值里的路径、描述信息，结合它对图片的常识性推断，再在对话里向你转述。所以如果 MCP 服务器返回的元信息很少，Claude 就会表现出“看图困难”的样子，解决方法是让 MCP 工具在返回时附带一段图片摘要，或者直接把图片路径放进去让它辅助分析。
3.2 Nano Banana 模型本身的特性，决定了你能怎么玩
Nano Banana 本质上是一个原生多模态模型，输入支持文本和图像，输出直接就是图像。这和 Stable Diffusion 那类先编码再扩散的架构不太一样，好处体现在两个地方：
- 图像编辑的一致性极强。你给它一张猫的正面照，要求“戴上墨镜”，墨镜会以符合透视关系的方式贴上去，猫的五官和毛色几乎不变。传统扩散模型要做到这个效果，需要额外的 ControlNet、Inpaint 模型层层配合，而 Nano Banana 靠指令理解直接完成。
- 支持多轮图像迭代。上一轮生成结果可以作为下一轮的输入，你在对话里连续说“再亮一点”“把背景换成沙滩”，它能顺着之前的输出继续改，而不是每一次都从噪声重新生成，这对“逐步精修”类工作流极其友好。
Nano Banana 的上下文窗口也比一般图像模型大不少，可以处理多张参考图同时输入。比如给三张不同角度的产品照片，让它生成一张包含所有视角的营销海报，它也能正确融合布局。
3.3 MCP 工具到底封装了哪些能力
我用的这个 MCP 服务器，核心工具大致有这么几类：
| 工具名 | 作用 | 典型参数 |
|---|---|---|
| generate_image | 文本生成图像 | prompt、size、aspect_ratio、reference_images |
| edit_image | 基于现有图像做局部编辑 | image_path、instruction、strength |
| describe_image | 对输入图片做内容理解与标注 | image_path |
| replace_background | 一键替换图像背景 | image_path、background_prompt |
说实话，工具列表不是官方唯一标准，不同封装版本暴露出的函数名可能有差异。但核心逻辑一致：能生成、能编辑、能理解。注册完以后建议先describe_image测一张本地图，确认整条链路是通的，再上手生成和编辑，排错时能少走很多弯路。
4. 实战记录：三个我在终端里真实跑通的图像任务
理论聊完了，直接上实操。以下三个案例是我在终端里实际跑过的，从输入指令到输出成功，每一步都记录了会话里的关键内容和结果形态。
4.1 文生图：给博客生成一张封面图
第一个任务最基础：一句话生成一张横版封面图。我当时的指令是：
帮我把 assets 目录下的 arch.png 作为参考图，生成一张博客封面，主题是“终端工作流的力量”，深蓝底色，画面中央有一个发光的终端窗口剪影，四周有抽象的数据流线条。尺寸要 1024x1024。Claude Code 很快判断出这属于“参照参考图 + 新增设计”的组合需求，调用了 generate_image，传参里除了 prompt，还把assets/arch.png的本地路径放进了 reference_images。几秒后返回了一个 JSON，大致长这样：
{ "status": "success", "file_path": "output/cover.png", "width": 1024, "height": 1024, "model": "nano-banana" }图片落在output/cover.png，Claude 随后在会话里补充了一句“参考图的整体构图被保留，文字区域留白较多，方便后续叠加标题”。这个提示本身说明模型确实读到了参考图的构图信息，而不只是在白纸上随机创作。
第一次跑通时我还有个多余的担心：Claude 会不会找不到assets/arch.png？实际不会，因为项目工作目录就是 Claude Code 的当前目录，它解析相对路径非常精准。
4.2 局部编辑：给产品图加一个营销角标
第二个任务更能体现 Nano Banana 的核心优势——保持主体不变的前提下做局部修改。我给了一张电饭煲产品图，指令是：
编辑 assets/rice-cooker.jpg，在图片左上角添加一个红色渐变的横幅，上面写“PRE-SALE”，保留电饭煲本体完整细节，不要遮挡产品的锅盖和按钮。这个指令涉及两层约束：位置约束（左上角）、语义约束（不能遮挡关键部件）。传统图生图模型往往顾此失彼，要么横幅贴到锅身上，要么电饭煲形状跟着重绘。Nano Banana 这次处理得相当稳，横幅自然地以约 45 度斜角贴在左上角，锅盖和按键区域完全没被改动。
我在编辑后多问了一句“目标物体有没有发生形变”，MCP 服务器没有二次分析的能力，但 Claude 通过路径读了图片的现有信息，并根据文件名和新建时间等信息给出了一个合理判断。这算一个提个醒：MCP 返回的信息越丰富，Claude 基于它的“汇报”就越有底气。
4.3 风格转换：把产品图转成水彩插画
第三个任务是风格迁移。我把一张户外咖啡壶的照片扔给它，要求“改成水彩插画风格，产品主体保持原样，背景变成纸张质感”。实际效果比预期好，水彩的“晕染感”主要集中在背景，产品轮廓没有糊掉，阴影区域也被重绘成手绘线条感。
风格转换这类任务特别适合在终端里反复迭代，因为不需要像网页版那样频繁上传下载。我跑完一张觉得背景太暗，下一句直接说“背景再亮一点，像早上十点的日光”，它会基于上一张输出继续微调。整个迭代过程在终端里一气呵成，生成结果始终落在同一个输出目录，旧文件自动被新版本覆盖，方便后续挑选。
三个任务跑下来，我的体验是：对指令的文字描述能力要求比网页版高，但换来的是“生成—查看—修改—落地”全流程不用离开编辑器。你在终端描述图片需求的方式，相当于在写一段高度浓缩的需求文档，越具体，结果越可控。
5. 绕不开的坑：图片路径、上下文长度、终端预览，一个都别落下
这条链路我踩过不少坑，不少问题反复出现，这里统一记录一下排查思路。
5.1 图片必须传本地路径，而不是“拖拽粘贴”
在终端里，你没法像在网页或者微信聊天框里那样，直接把图片拖进会话让 Claude “看”。Claude Code 的交互模型是纯文本的，你能给它的，只有文件的路径。很多人第一次编辑图片时把一张截图拖进终端，模型只能看到一串转义字符，自然就会懵住。
正确做法是把图片放到项目工作目录内，然后在指令里写相对路径，或者直接写绝对路径。我自己写绝对路径的优先级更高，因为 MCP 服务器进程的工作目录不一定是 Claude Code 的项目根目录，如果两边对相对路径的理解不一致，图片就会凭空“消失”。用绝对路径能彻底规避这个歧义。
5.2 环境变量没传透，API Key 永远读不到
MCP 服务器的独立进程并不是从终端继承所有环境变量的。你之前在.bashrc或某个 shell 配置文件里导出的 NANO_BANANA_API_KEY，Claude Code 内部未必会原样传给 MCP 子进程。最直观的表现是：第一次调用工具，几秒钟后返回一个 401 认证错误。
处理方式是最老土也最有效的一种——直接在注册时用--env显式指定：
claude mcp add nano-banana --env NANO_BANANA_API_KEY=你的API Key -- npx -y nano-banana-mcp.mcp.json里也同理，必须把 env 字段写进配置。排查时可以在终端里直接运行一次nano-banana-mcp的某个子命令，确认它自己能不能拿到 Key，这样能把问题定位在“环境变量传递”还是“工具本身坏”上。
5.3 上下文膨胀：图片太多会直接把对话窗口塞爆
这是我最想强调的一个坑。Claude Code 的上下文窗口是有限的，而图像类 MCP 工具返回的数据非常容易“爆窗”。尤其是一些封装版本会把图片转成 Base64 字符串塞进返回结果，一张 1024x1024 的图 Base64 编码后可能直接占用几万 token，多来两张，整个会话上下文就快要见底了。
我自己后续的做法是：优先选择支持“返回本地路径 + 简短描述”的 MCP 服务器版本。如果你用的版本默认返回大段 Base64，建议看一下它的配置文件项，很多开源实现都提供了return_mode=path这类选项。多轮图像迭代时，也不要每轮都传参考图，只在第一轮传一次，后续指令基于已经生成的本地路径推进，能省下大量上下文空间。
5.4 终端里看不到图片，怎么即时预览
终端是字符界面，不能直接“弹”出一张 PNG。跑通了生成任务却看不到结果，会严重影响迭代效率。这里有几个可以补位的终端预览工具：
- iTerm2 内置了 imgcat 命令，直接在终端渲染图片，macOS 用户首选。
- 跨平台工具 chafa 能把图片转成 ANSI 色块，兼容几乎所有终端。
- 另一个轻量选项是 viu，支持 iTerm2、Kitty 等协议终端。
如果你是远程开发，比如 SSH 到服务器或者 WSL2 里操作，建议把生成的图片路径映射出来，本地用 VS Code 的图片预览插件打开，或者直接配置 MCP 服务器把图片另存到一个同步目录，本地实时预览。
5.5 MCP 工具报错的通用排查路线
遇到工具执行失败时，我先看三块信息：Claude Code 会话里打印的错误信息、MCP 服务器的终端日志（如果是前台启动的话）、以及配置里的 command 本身是否可执行。错误信息不同，处理方式也不同，这里整理一个排查参考：
| 错误现象 | 大概率原因 | 处理方式 |
|---|---|---|
| 401 / auth error | API Key 无效或未传递 | 检查 env 配置，直接在 shell 里测试 Key 是否可用 |
| file not found | 图片路径错位 | 改用绝对路径，确认图片确实存在于当前机器 |
| context length exceeded | Base64 或大量图片塞爆上下文 | 切换 return_mode=path，减少参考图数量 |
| timeout | 图片过大或网络异常 | 降低图片分辨率，重试一次，确认网络可达 |
| tool not found | MCP 服务器没注册成功 | 运行 claude mcp list，检查配置与命令名 |
这五类坑覆盖了我遇到的绝大多数问题。剩下的小问题多半是版本不匹配，Nano Banana MCP 这个生态更新速度很快，隔几个星期再看觉得像是两个项目，保持跟踪就好。
6. 从“能出图”到“随手出图”：终端图像工作流的进阶玩法
基础链路跑通之后，我很快就不满足于“一句一句命令地出图”了。把它变成一个真正顺手的工作流，还需要做几件事，分享三个我自己已经在生产环境里用的玩法。
6.1 用 shell 函数把出图流程包装成一条命令
我平时最常用的操作，是让 Nano Banana 基于一个固定风格模板批量产出素材。这个需求可以直接封装成一个 shell 函数，放在~/.zshrc或~/.bashrc里：
quicknb() { claude -p "调用 nano-banana 的 generate_image 工具，生成一张 1024x1024 图片。需求：$1。保存到 assets/generated/" }用法就变成了一句：
quicknb "博客封面，主题为终端中的图像编辑，深色背景，中央有一个发光的香蕉和终端窗口"这个函数执行完，图片直接落在assets/generated/里。更重要的是，因为走的是claude -p这种非交互模式，后续还能把它接进其他脚本，比如配合定时任务批量生成每日海报。这种“后台跑图”的能力，网页版完全给不到。
6.2 结合终端复用工具，把写作/编码/出图同时铺开
图像生成不是一次性动作，它需要迭代。我强烈建议配合 tmux 这类终端复用工具，把工作区切成两到三个面板：左面板写代码或写文档，右上方面板跑 Claude Code 让它出图，右下方面板用 chafa 实时预览生成结果。这样你在左侧改代码的时候，右侧已经自动出图了，改完代码抬头扫一眼图片效果，马上给出下一轮修改指令。
我自己最常用的是 tmux 三栏布局，Claude Code 在左下，预览窗口在右下，iTerm2 的 imgcat 命令配合刷新脚本，每生成一张新图就自动渲染一次。整个流程像是一个“图像渲染面板”被塞进了终端，和编码过程完全同构。
6.3 把出图能力接进文档与素材自动化流程
既然图片能实时落到项目目录，它就可以参与任何自动化流程。一个典型的场景是博客封面自动生成：
- 项目里写好一篇 markdown，
- 脚本读取 frontmatter 里的标题，构造出封面描述词，
- 调用 quicknb 或者直接调 Claude Code API，生成封面图，
- 图片以固定命名规则落到
static/images/， - 文章模板自动引用这张封面。
类似的玩法还有 CI 脚本里为每个 PR 生成视觉预览图、内部组件库根据当前版本自动生成宣传 banner，甚至本地跑一个监听目录变化的脚本，新截图放进 inotify 监控目录，立刻自动触发 Nano Banana 的“简化标注”任务。这个思路一旦打开，可扩展的空间非常大。
6.4 别忘了 MCP 是开放的，Nano Banana 只是其中一个插槽
Claude Code 的 MCP 生态并不只有图像生成这一种用法。这套“标准接口 + 外部工具”的架构，理论上可以接文件系统、数据库、浏览器自动化、代码搜索等任何你想接的能力。Nano Banana 作为图像能力的一个插槽，给我最大的启发是：终端里的 AI Agent，过去只能处理“代码”这种纯文本产物，现在可以把图像、设计、审美类任务也纳入到同一条指令流里。
我也试过用同样的 MCP 机制接入其他模型的服务，协议完全兼容，只需要按照工具定义写好配置即可。这意味着你看中的不是某一个具体工具，而是一整套可以自由组合的生产力积木。
玩到这一步，我个人的体会特别朴素：技术方案贵在“顺手”。Claude Code 加 Nano Banana MCP 这个组合，不一定是最强大的图像生成方案，但它把图像能力和开发流程融到一起，减少的是来回切换的工具损耗。现在好多朋友喜欢在终端里搞各种整合，如果能把图像这类非结构化产出也纳入终端工作流，你的动手效率会明显不一样。
最后分享一个我最近才养成的习惯：临时需要一张配图时，我不会去找“哪个网站能免费生成”，而是先打开一个终端面板，敲一句 prompt，让 Nano Banana 直接出一版粗稿。粗稿不满意就直接下修改指令，基本一两个来回就能投入使用。这个习惯一旦建立起来，工具本身就不再重要，重要的是你已经形成了一条“文字描述—视觉产出—迭代修正”的闭环，而它离你的键盘只有半秒钟。
