Claude Code 通过 MCP 接入 Nano Banana 实现 AI 修图

1. 为什么要在 Claude Code 里接一个修图能力

1.1 开发工作流里被忽视的“图片断点”

写代码的人大多有过这种体验：项目文档里需要一张架构示意图，UI 稿需要快速生成一个占位图，README 里想放一张演示截图，或者给客户做原型演示时临时需要几张风格统一的配图。这些需求本身不复杂，但它们的共同点是——它们会打断你的编码节奏。

你正在 Claude Code 里专注地改一个模块，突然意识到需要一张图。于是你切到浏览器，打开某个在线修图工具，上传、等待、调整、下载，再切回编辑器，把图片拖进项目目录。这一套动作下来，少则三五分钟，多则十几分钟，思路断了，上下文丢了。更麻烦的是，如果这张图还需要反复调整尺寸、风格、背景，那这个循环就要重复好几遍。

我自己在做一个前端项目时就遇到过这种情况。当时需要给一个组件库生成一批风格一致的图标占位图，一共二十多张。如果按传统方式，我得在修图工具里一张张处理，或者写脚本调用某个图像 API，但后者又涉及到密钥管理、请求封装、错误处理，为了几张图写一套代码，性价比太低。

问题的本质不是“修图难”，而是“修图这件事和开发环境是割裂的”。Claude Code 已经能帮我们读写文件、执行命令、理解项目上下文，但它默认不具备图像处理能力。而 MCP（Model Context Protocol）的出现，恰好给了我们一个把外部能力“插”进 Claude Code 的标准接口。

1.2 MCP 到底解决了什么问题

MCP 这个词最近出现频率很高，但很多人对它的理解还停留在“又一个协议”的层面。用一句大白话解释：MCP 就是让 AI 助手能够调用外部工具的一套标准约定。你可以把它理解成 AI 世界的 USB 接口——只要外部服务按照这个接口规范暴露自己的能力，AI 助手就能像插 U 盘一样把它接进来用。

在 Claude Code 的场景里，MCP 的价值尤其明显。Claude Code 本身是一个运行在终端里的编程助手，它能读文件、写文件、跑命令，但它的能力边界是由它内置的工具集决定的。MCP 让你可以扩展这个工具集，把图像处理、数据库查询、第三方 API 调用等能力接进来，而且这些能力是以“工具”的形式暴露给模型的，模型可以自主决定什么时候调用、传什么参数。

这就意味着，你不需要离开 Claude Code，不需要手动切换工具，只需要用自然语言描述你的需求，Claude Code 就能通过 MCP 调用对应的图像处理服务，把结果直接落到你的项目目录里。

1.3 Nano Banana 和 Ace Data Cloud 在链路中的位置

Nano Banana 是 Google 推出的图像生成与编辑模型，它在图像编辑任务上的表现相当突出，尤其是对已有图片的局部修改、风格迁移、背景替换这类操作，响应质量和速度都不错。相比从零生成一张图，Nano Banana 更擅长“在已有基础上改”，这恰好匹配开发工作流中“我有一张图，但需要调整”的常见场景。

Ace Data Cloud 则提供了把这些模型能力封装成 MCP 服务的通道。它把 Nano Banana 的图像编辑能力包装成符合 MCP 协议的工具，暴露给 Claude Code 调用。整条链路是这样的：你在 Claude Code 里用自然语言描述修图需求，Claude Code 通过 MCP 协议把请求发给 Ace Data Cloud 的服务端，服务端调用 Nano Banana 完成图像处理，处理结果返回后由 Claude Code 写入你指定的文件路径。

这个链路里，你不需要写任何胶水代码，不需要管理 API 密钥的注入位置（配置一次即可），也不需要关心请求的序列化和反序列化。MCP 把这些脏活累活都屏蔽掉了。

1.4 这套方案适合谁用

如果你符合下面任意一条，这套方案值得你花时间配置：

• 经常在项目里需要生成或修改图片，但不想离开编辑器
• 已经在用 Claude Code，想扩展它的能力边界
• 对 MCP 感兴趣，想找一个真实可用的场景来理解它
• 需要批量处理图片，但不想为此写一套脚本
• 做原型开发，需要快速产出视觉素材

反过来说，如果你只是偶尔修一张图，用现成的在线工具可能更快。这套方案的价值在于“高频”和“流程内”，它把修图这件事从“切换工具”变成了“说一句话”。

2. 环境准备与 MCP 接入的核心逻辑

2.1 Claude Code 的安装与基础确认

在接入 MCP 之前，得先确保 Claude Code 本身能正常工作。Claude Code 的安装方式根据操作系统不同略有差异，但核心步骤是一致的。

macOS 和 Linux 环境下，通常通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code

Windows 环境下，如果你用的是 WSL，步骤和 Linux 一致；如果是在原生 Windows 终端里，建议先确认 Node.js 版本在 18 以上，然后同样用 npm 安装。安装完成后，在终端输入claude命令，如果能进入交互界面，说明基础环境没问题。

这里有个容易被忽略的点：Claude Code 需要登录才能使用。如果你所在的组织禁用了订阅访问，可能会遇到权限相关的提示。这种情况下需要确认你的账号状态，或者使用支持的方式完成认证。认证完成后，Claude Code 会在本地保存凭证，后续使用不需要重复登录。

注意：安装完成后建议先跑一个简单任务验证，比如让它读一个本地文件并总结内容。这一步能确认模型调用链路是通的，避免后面 MCP 配置出问题时分不清是哪个环节的锅。

2.2 MCP 配置文件的存放位置与格式

Claude Code 的 MCP 配置是通过一个 JSON 文件管理的。这个文件的位置根据你的使用方式不同会有差异：

• 如果是在项目目录下使用，配置文件通常放在项目根目录的.claude文件夹里
• 如果是全局配置，放在用户主目录下的.claude文件夹里

配置文件的名称一般是mcp.json或者直接在settings.json里以mcpServers字段声明。具体格式如下：

{ "mcpServers": { "ace-data-cloud": { "command": "npx", "args": ["-y", "@ace-data-cloud/mcp-server"], "env": { "ACE_DATA_CLOUD_API_KEY": "你的密钥" } } } }

这段配置的含义是：告诉 Claude Code，有一个叫ace-data-cloud的 MCP 服务，启动方式是执行npx @ace-data-cloud/mcp-server这个命令，并且把 API 密钥通过环境变量传进去。

这里的关键点是command和args。MCP 服务本质上是一个本地进程，Claude Code 会按照你配置的命令去启动它，然后通过标准输入输出（stdio）和这个进程通信。所以command必须是系统能识别的可执行命令，args是传给这个命令的参数。

2.3 为什么选择 stdio 而不是 HTTP 传输

MCP 支持多种传输方式，常见的有 stdio（标准输入输出）和 HTTP/SSE。在 Claude Code 的场景里，stdio 是更自然的选择，原因有几个。

第一，stdio 模式下 MCP 服务是作为 Claude Code 的子进程运行的，生命周期由 Claude Code 管理。你不需要单独启动一个服务，也不需要担心端口占用。Claude Code 启动时会把配置里的 MCP 服务拉起来，退出时自动清理。

第二，stdio 通信不经过网络，数据在本地进程间直接传递，延迟更低，也没有网络暴露面。对于图像处理这种需要传输 base64 编码图片数据的场景，本地通信的优势很明显。

第三，配置更简单。HTTP 模式需要你手动管理服务端的启动、端口、健康检查，而 stdio 模式只需要一行命令配置。

当然，stdio 也有它的局限。如果 MCP 服务本身需要长时间运行、被多个客户端共享，那 HTTP 模式更合适。但对于个人开发工作流，stdio 的简洁性压倒一切。

2.4 密钥管理与安全边界

API 密钥的处理是接入外部服务时最需要谨慎的环节。在上面的配置里，密钥是通过env字段注入的，这意味着密钥会以环境变量的形式存在于 MCP 服务进程中。

几个实操建议：

• 不要把密钥硬编码在会提交到版本控制的文件里。如果.claude/mcp.json在项目目录下，确保它被.gitignore排除。
• 优先使用全局配置而不是项目配置来存放密钥，这样密钥不会跟着项目走。
• 如果团队协作需要共享 MCP 配置，把密钥部分抽出来，用环境变量引用，比如"ACE_DATA_CLOUD_API_KEY": "${ACE_DATA_CLOUD_API_KEY}"，然后在各自的 shell 环境里设置。
• 定期轮换密钥。MCP 服务通常会在启动时读取密钥，轮换后重启 Claude Code 即可生效。

提示：配置完成后，可以在 Claude Code 里输入/mcp命令查看当前已加载的 MCP 服务列表。如果配置正确，应该能看到ace-data-cloud出现在列表里，并且状态是已连接。

3. 核心工具能力拆解与调用方式

3.1 Ace Data Cloud MCP 暴露了哪些工具

MCP 服务接入后，它暴露的工具会自动出现在 Claude Code 的可用工具列表里。Ace Data Cloud 这套服务围绕 Nano Banana 的图像编辑能力，通常会暴露以下几类工具：

具体工具名称和参数以实际服务暴露的为准，但核心逻辑是一致的：输入是图片路径或描述，输出是处理后的图片文件。

这里的设计思路值得说一下。工具的参数设计倾向于“文件路径进、文件路径出”，而不是“base64 进、base64 出”。这样做的好处是，Claude Code 可以直接操作项目里的文件，处理结果直接落盘，不需要在对话里传输大段二进制数据。对于动辄几百 KB 的图片来说，这个设计能显著降低上下文开销。

3.2 用自然语言触发工具调用的机制

MCP 工具接入后，你不需要记住工具的具体名称和参数格式。Claude Code 会根据你的自然语言描述，自动判断该调用哪个工具、传什么参数。

比如你说：“把assets/logo.png的背景去掉，输出到assets/logo-transparent.png”，Claude Code 会识别出这是一个背景移除任务，找到对应的 MCP 工具，把文件路径作为参数传进去，执行完成后告诉你结果。

这个过程的背后是模型对工具描述的理解。每个 MCP 工具都会附带一段描述文本，说明它是干什么的、参数是什么含义。模型在规划任务时，会把这些描述和你的需求做匹配，选出最合适的工具。

这也意味着，你的描述越具体，工具调用的准确率越高。与其说“帮我处理一下这张图”，不如说“把这张图的尺寸改成 800x600，保持宽高比，输出到指定路径”。前者模型需要猜你的意图，后者意图明确，直接映射到工具参数。

3.3 图片路径的处理规则

在实际使用中，路径处理是最容易出问题的地方。MCP 服务进程的工作目录和 Claude Code 的工作目录可能不一致，这会导致相对路径解析出错。

稳妥的做法是始终使用绝对路径，或者在描述里明确说明相对于哪个目录。比如：

把 /Users/yourname/project/assets/hero.png 的色调调暖一些，输出到同目录下的 hero-warm.png

如果你在项目根目录下启动 Claude Code，也可以使用相对于项目根目录的路径，但前提是 MCP 服务的工作目录也被设置成了项目根目录。这一点在配置 MCP 服务时可以通过cwd参数指定：

{ "mcpServers": { "ace-data-cloud": { "command": "npx", "args": ["-y", "@ace-data-cloud/mcp-server"], "cwd": "/Users/yourname/project", "env": { "ACE_DATA_CLOUD_API_KEY": "你的密钥" } } } }

注意：如果遇到“文件找不到”的错误，第一件事就是检查路径。先确认文件确实存在，再确认路径是绝对的还是相对的，最后确认 MCP 服务的工作目录设置是否正确。

3.4 批量处理的实现思路

单张图片处理跑通后，批量处理就是自然延伸。有两种方式：

第一种是在一次对话里列出多个文件，让 Claude Code 依次处理。比如：“把assets/目录下所有 png 文件的尺寸都改成 512x512，输出到assets/resized/目录”。Claude Code 会遍历目录，对每个文件调用一次工具。

第二种是写一个简单的 shell 脚本，在脚本里调用 Claude Code 的非交互模式。Claude Code 支持通过命令行参数执行一次性任务，你可以把批量逻辑写在脚本里，循环调用。

第一种方式适合文件数量不多、需要人工确认的场景；第二种方式适合文件数量大、处理逻辑固定的场景。我自己的经验是，二十张以内的图片用第一种方式更省事，超过二十张就值得写脚本了。

4. 完整实操流程与关键环节

4.1 从零开始：配置到第一次调用

假设你是一个全新环境，下面是完整的操作序列。

第一步，确认 Claude Code 可用。在终端执行claude --version，如果能输出版本号，说明安装没问题。

第二步，获取 Ace Data Cloud 的 API 密钥。这个密钥通常在你的 Ace Data Cloud 账号控制台里生成，复制出来备用。

第三步，创建或编辑 MCP 配置文件。如果项目目录下没有.claude文件夹，先创建：

mkdir -p .claude

然后创建mcp.json：

touch .claude/mcp.json

把前面提到的配置内容写进去，替换掉密钥占位符。

第四步，启动 Claude Code。在项目根目录下执行claude，进入交互界面。

第五步，验证 MCP 服务加载。输入/mcp，查看服务列表。如果看到ace-data-cloud且状态正常，说明配置成功。

第六步，准备一张测试图片。随便找一张 png 或 jpg 放到项目目录下，比如test.png。

第七步，发起第一次调用。在 Claude Code 里输入：

把 test.png 的尺寸改成 400x400，输出到 test-resized.png

如果一切正常，几秒到几十秒后，你会在项目目录下看到test-resized.png。

4.2 参数选择的计算过程

图像处理里几个关键参数的选择，背后是有计算逻辑的，不是随便填的。

尺寸调整：如果你要保持宽高比，只需要指定宽度或高度其中一个，另一个按原图比例算出来。比如原图是 1200x800，你想把宽度改成 600，那高度就是 600 * (800/1200) = 400。如果你同时指定宽高且比例不一致，图片会被拉伸变形。大部分场景下建议保持宽高比。

文件大小控制：图片文件大小主要取决于分辨率和压缩质量。如果你需要把图片控制在某个大小以内，比如 200KB，可以先按目标分辨率导出，如果还是太大，再降低压缩质量。png 是无损格式，文件通常较大；jpg 是有损格式，可以通过质量参数控制大小。对于网页用的图片，jpg 质量设在 80 左右通常能在视觉质量和文件大小之间取得不错的平衡。

批量处理的命名规则：批量处理时，输出文件的命名要有规律，否则处理完一堆文件你分不清哪个是哪个。常见的做法是在原文件名后加后缀，比如logo.png处理后变成logo-resized.png、logo-warm.png。如果有多轮处理，后缀可以叠加。

4.3 一个真实的修图任务拆解

我拿一个实际项目里的需求来演示。当时我在做一个落地页，需要一张 hero 区域的背景图。原始素材是一张从图库下载的风景照，但有几个问题：色调偏冷，和品牌色不搭；尺寸太大，有 4000 多像素宽；文件体积 3MB 多，直接放网页上加载太慢。

我的处理流程是这样的：

第一轮，调整色调。在 Claude Code 里输入：“把assets/hero-raw.jpg的色调调暖，增加一些橙色调，输出到assets/hero-warm.jpg”。这一步调用的是图像编辑工具，Nano Banana 会根据描述对图片做风格调整。

第二轮，调整尺寸。输入：“把assets/hero-warm.jpg的宽度改成 1920，保持宽高比，输出到assets/hero-1920.jpg”。这一步是尺寸调整，计算逻辑前面说过。

第三轮，压缩体积。输入：“把assets/hero-1920.jpg的质量压缩到 80，输出到assets/hero-final.jpg”。这一步控制文件大小。

三轮下来，最终得到的图片宽度 1920，色调匹配品牌，文件大小控制在 300KB 左右。整个过程没有离开 Claude Code，每轮处理的结果都能立即在项目里看到。

4.4 把修图嵌入开发流程的几种模式

配置好之后，修图能力可以嵌入到几种不同的开发场景里。

文档配图模式：写 README 或技术文档时，需要配图就直接在 Claude Code 里生成或修改，输出到docs/images/目录，然后在 markdown 里引用。整个过程不需要切换工具。

UI 占位图模式：前端开发时，很多图片位置在开发阶段用占位图就行。你可以让 Claude Code 批量生成一批统一风格的占位图，尺寸和命名都按规范来，等设计稿到位后直接替换。

原型演示模式：给客户做原型演示时，需要一些看起来像那么回事的配图。用 Nano Banana 基于草图或简单描述生成风格统一的图片，比到处找图库快得多。

资源优化模式：项目上线前，对图片资源做一轮批量优化——统一尺寸、压缩体积、转换格式。这些操作在 Claude Code 里描述一遍就能批量执行。

这几种模式的共同点是：修图不再是独立环节，而是开发流程里的一个自然动作。你不需要为它专门开辟一段时间，它就像保存文件一样自然地发生在编码过程中。

5. 常见问题排查与避坑经验

5.1 MCP 服务启动失败的排查顺序

MCP 服务启动失败是最常见的问题，表现是/mcp命令里看不到服务，或者服务状态显示错误。排查按以下顺序来：

第一，检查命令是否可执行。配置里的command是npx，确认你的系统里 npx 可用。在终端执行npx --version，如果报错说明 Node.js 环境有问题。

第二，检查包名是否正确。args里的包名如果拼错，npx 会去下载一个不存在的包，然后失败。可以先在终端手动执行一次npx -y @ace-data-cloud/mcp-server，看看能不能正常启动。如果这个命令本身就报错，那问题不在 Claude Code，而在包本身。

第三，检查密钥是否有效。密钥错误通常不会导致服务启动失败，但会在调用工具时报错。如果服务能启动但工具调用失败，优先检查密钥。

第四，检查配置文件格式。JSON 格式对逗号和引号很敏感，一个多余的逗号就会导致解析失败。可以用在线的 JSON 校验工具检查一下配置文件。

第五，查看日志。Claude Code 在启动 MCP 服务时，如果服务进程输出了错误信息，这些信息通常会显示在 Claude Code 的日志里。用claude --debug启动可以看到更详细的日志。

5.2 工具调用超时与重试策略

图像处理是计算密集型任务，尤其是高分辨率图片的编辑，处理时间可能达到几十秒。如果超时设置太短，请求会在处理完成前被中断。

Claude Code 对 MCP 工具调用有默认的超时时间。如果遇到超时，有几个应对方式：

• 降低图片分辨率后再处理。先把大图缩小，处理完再放大（如果确实需要大尺寸）。
• 把复杂任务拆成多步。比如“调色+改尺寸+压缩”分三次调用，每次的任务更简单，耗时更短。
• 检查网络状况。虽然 MCP 服务在本地，但它调用的 Nano Banana 服务在远端，网络延迟会影响总耗时。

提示：如果某个操作反复超时，可以先在终端里用 curl 直接调用 Ace Data Cloud 的 API，确认服务端本身是否正常。这样能把问题范围缩小到“是 MCP 配置问题”还是“是服务端问题”。

5.3 图片格式与兼容性坑

不是所有图片格式都能被顺利处理。几个常见的坑：

格式支持：png、jpg、webp 通常没问题，但一些特殊格式如 heic、tiff 可能不被支持。如果遇到格式错误，先用系统自带的工具转成 png 或 jpg 再处理。

透明通道：png 支持透明通道，jpg 不支持。如果你把一张带透明背景的 png 转成 jpg，透明区域会变成黑色或白色。需要透明背景的场景，全程用 png。

色彩空间：有些图片是 CMYK 色彩空间（印刷用），而图像处理服务通常按 RGB 处理。CMYK 图片直接处理可能出现颜色偏差。处理前先转成 RGB。

文件大小限制：MCP 服务对输入图片的大小通常有上限，比如 10MB 或 20MB。超过限制的图片需要先压缩或缩小。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是路径里的空格。macOS 下很多目录名带空格，比如My Project。如果路径里有空格，在配置或描述里没有正确处理，会导致文件找不到。解决办法是路径用引号包起来，或者干脆避免在项目路径里使用空格。

第二个坑是并发调用。我试过一次让 Claude Code 同时处理五张图片，结果部分请求失败。后来改成串行处理，虽然慢一点但稳定。MCP 服务对并发请求的处理能力有限，批量任务建议串行执行。

第三个坑是输出文件覆盖。如果输出路径和输入路径相同，有些工具会直接覆盖原文件，有些会报错。我的习惯是输出路径永远加后缀，保留原文件，这样出问题还能回退。

第四个坑是描述歧义。有一次我说“把图片调亮一点”，结果模型把整张图的对比度也改了。后来我改成“把图片的亮度提高 20%，其他参数不变”，结果就符合预期了。描述越精确，结果越可控。

6. 能力扩展与工作流优化

6.1 把修图能力接入自动化脚本

Claude Code 支持非交互模式，可以通过命令行参数直接执行任务。这意味着你可以把修图逻辑写进 shell 脚本，在构建流程里自动执行。

比如，你可以在package.json里加一个脚本：

{ "scripts": { "optimize-images": "claude -p '把 assets/raw/ 目录下所有 jpg 文件的宽度改成 1200，质量压缩到 80，输出到 assets/optimized/'" } }

这样每次构建前跑一下npm run optimize-images，图片资源就自动处理好了。这个模式特别适合图片资源经常变动的项目。

6.2 与其他 MCP 服务的组合使用

Ace Data Cloud 的修图能力只是 MCP 生态里的一块。你可以同时配置多个 MCP 服务，让 Claude Code 在不同任务间自动切换。

比如，你可以同时接入一个文件管理 MCP 和一个修图 MCP。当你说“把设计稿目录里的图片都处理一下，然后整理到资源目录”时，Claude Code 会先调用文件管理工具遍历目录，再调用修图工具处理图片，最后再调用文件管理工具移动文件。整个过程你只需要说一句话。

这种组合能力是 MCP 架构的核心价值。每个 MCP 服务专注做好一件事，Claude Code 负责编排。你不需要一个“什么都能干”的巨型服务，而是用多个小服务拼出完整能力。

6.3 针对不同场景的参数预设

高频使用的参数组合可以固化成预设，减少每次描述的负担。虽然 MCP 本身不直接支持预设，但你可以在项目里维护一个“配方”文档，把常用场景的参数写清楚，需要时直接复制。

比如：

把这些模板放在项目文档里，需要时直接引用，比每次重新想要快得多。

6.4 性能与成本的平衡

图像处理服务通常是按调用次数或处理量计费的。在高频使用场景下，成本会累积。几个控制成本的思路：

• 能本地做的操作不要走远端服务。比如纯尺寸调整，用本地的图像处理库（如 ImageMagick）就能完成，没必要调用远端模型。
• 批量任务先小规模测试。确认参数和效果符合预期后，再跑全量。
• 缓存处理结果。同一张图同样的处理参数，结果应该是一样的，没必要重复处理。
• 合理选择分辨率。不是所有场景都需要高分辨率，网页用图 1920 宽通常够了，没必要处理 4000 宽的图。

我自己的做法是，把“需要 AI 理解语义”的任务（如风格调整、背景移除）交给 MCP 服务，把“纯机械操作”的任务（如尺寸调整、格式转换）交给本地工具。这样既发挥了 AI 的优势，又控制了成本。

6.5 后续可以扩展的方向

这套工作流跑通后，有几个自然的扩展方向。

一是接入更多图像处理能力，比如批量加水印、生成图片描述文本、图片内容审核等。这些能力都可以通过 MCP 服务的形式接入。

二是把修图能力和其他开发工具链结合。比如在 CI 流程里自动处理新增的图片资源，或者在文档生成流程里自动配图。

三是把常用的修图任务封装成 Claude Code 的自定义命令。Claude Code 支持自定义斜杠命令，你可以把一段常用的修图指令定义成一个命令，比如/optimize-hero，一键执行整套处理流程。

四是探索多模型组合。Nano Banana 在编辑任务上表现好，但其他模型可能在某些特定风格上更强。通过 MCP 接入多个模型服务，根据任务类型选择最合适的模型。

我在实际使用中最大的体会是，这套方案的价值不在于“修图”本身，而在于它把修图变成了开发工作流里一个不需要思考的动作。你不需要决定用什么工具、不需要切换窗口、不需要手动传文件，只需要描述你想要什么，剩下的交给 Claude Code 和 MCP 服务。这种“意图到结果”的短路径，才是它真正省时间的地方。

最后分享一个小技巧：如果你经常处理同一类图片，可以把处理指令写成一个文本片段存在项目里，每次需要时直接粘贴到 Claude Code 里，改一下文件路径就行。这比每次重新组织语言快得多，也能保证参数的一致性。