1. 为什么要在 OpenCode 里接入 NanoBanana MCP1.1 一个真实的工作流痛点做开发的人大概都有过这种体验写代码写到一半需要给项目配一张架构示意图或者给文档补一张流程图又或者临时要处理一张截图——裁剪、标注、加箭头、打码。这时候你不得不切出编辑器打开浏览器或者本地图像软件折腾半天再切回来。思路断了节奏也乱了。OpenCode 这类终端里的 AI 编程助手解决的是代码上下文里的智能补全和对话问题但它默认不具备图像编辑能力。而 NanoBanana 这类图像编辑服务能力很强却通常以网页或独立 API 的形式存在跟你的代码工作流是割裂的。把这两者用 MCP 协议接起来本质上是让图像编辑变成你编程会话里的一个可调用工具不用离开终端就能完成。这就是我折腾这套方案的出发点不是追求技术炫技而是减少上下文切换带来的效率损耗。如果你每天有大量时间泡在 OpenCode 里写代码、调 bug、写文档同时又经常需要处理图像那这套接入方案值得你花半小时配一次。1.2 MCP 到底是个什么东西MCP 全称 Model Context Protocol翻译过来叫模型上下文协议。你可以把它理解成 AI 应用和外部工具之间的一个标准插座。以前每接一个工具都要为这个 AI 应用单独写一套适配代码有了 MCP工具方只要按协议暴露自己的能力工具、资源、提示词模板任何支持 MCP 的客户端都能直接调用。打个生活化的比方MCP 就像 USB-C 接口。以前每个设备一个专用充电口现在统一了插上就能用。OpenCode 是支持 MCP 的客户端NanoBanana 如果提供了 MCP Server或者有社区封装的 MCP Server那就能被 OpenCode 直接调用。这里要区分三个概念很多人一开始会搞混MCP Host宿主就是 OpenCode 本身负责发起调用、管理会话。MCP Client客户端Host 内部用来跟 Server 通信的模块通常你感知不到。MCP Server服务端真正干活的比如 NanoBanana 的图像编辑能力封装。理解了这三层后面配置的时候你就知道每一行配置在干什么而不是照抄一堆看不懂的 JSON。1.3 接入之后能做什么接入完成后你在 OpenCode 的对话里可以直接说帮我把这张图裁剪成 16:9 并加上标题文字OpenCode 会调用 NanoBanana 的 MCP 工具去执行返回处理后的结果。具体能覆盖的场景包括给技术文档批量生成配图、示意图对截图做裁剪、缩放、格式转换给图片加标注、水印、文字说明简单的风格化处理用于演示素材需要说明的是具体能力边界取决于 NanoBanana 暴露了哪些 MCP 工具。我下面讲的方法论是通用的先确认 Server 提供了什么工具再决定怎么在 OpenCode 里调用。这一点比记住某个具体命令重要得多。1.4 适合谁来参考这篇内容适合三类人一是已经在用 OpenCode、想扩展它能力边界的开发者二是对 MCP 协议好奇、想找个真实场景练手的人三是团队里负责搭工具链、想把图像处理纳入自动化流程的人。如果你完全没接触过 OpenCode 或 MCP建议先花点时间把基础概念过一遍否则配置环节容易卡壳。2. 接入前的环境准备与方案选型2.1 先确认 OpenCode 的版本和 MCP 支持情况不同版本的 OpenCode 对 MCP 的支持程度不一样。我踩过的第一个坑就是照着网上的教程配了半天结果发现自己的版本压根不支持某个配置字段。所以第一步永远是确认版本。在终端里执行opencode --version拿到版本号后去官方文档核对 MCP 相关章节。一般来说较新的版本会支持在配置文件里声明mcpServers字段。如果你用的是比较老的版本可能需要先升级。升级命令通常是包管理器那一套比如# 假设通过 npm 全局安装 npm update -g opencode注意升级前先备份你的配置文件尤其是自定义的模型、快捷键设置。我有一次升级完发现配置被重置白折腾半小时。2.2 确认 NanoBanana 的 MCP Server 形态NanoBanana 的 MCP 接入方式常见的有两种接入形态特点适用场景本地 stdio Server通过标准输入输出通信进程本地启动单机使用配置简单远程 HTTP/SSE Server通过网络通信需要地址和鉴权团队共享或服务方托管本地 stdio 方式最省心不需要处理网络和鉴权适合个人开发者。远程方式适合多人协作但要考虑网络稳定性和密钥管理。判断方法很简单看 NanoBanana 官方或社区提供的 MCP Server 文档里面会写明启动命令。如果是npx xxx或python xxx.py这种基本就是 stdio如果是给你一个 URL那就是远程方式。2.3 依赖环境检查清单在动手配置前把下面这些确认一遍能省掉后面 80% 的报错Node.js 版本如果 MCP Server 是 npm 包通常要求 Node 18 以上。用node -v检查。Python 版本如果是 Python 包一般要求 3.10 以上。用python --version检查。网络连通性远程 Server 需要能访问对应域名本地 Server 需要能下载依赖包。API 密钥NanoBanana 大概率需要密钥提前在账户后台生成好别等到配置时才发现没权限。磁盘空间本地 Server 首次运行会下载依赖留出几百 MB 空间。我习惯把这些检查做成一个脚本每次换机器先跑一遍echo Node: $(node -v 2/dev/null || echo 未安装) echo npm: $(npm -v 2/dev/null || echo 未安装) echo Python: $(python --version 21 || echo 未安装) echo pip: $(pip --version 21 || echo 未安装)2.4 方案选型为什么优先本地 stdio在能选的情况下我强烈建议先用本地 stdio 方式跑通。原因有三第一排错链路短。本地进程日志直接打到终端出问题一眼能看到。远程方式还要排查网络、鉴权、服务端状态变量太多。第二延迟低。图像处理本身耗时如果通信再绕一圈网络体验会很差。第三密钥不出本机。本地方式密钥存在你自己的配置文件里不经过第三方中转心理上更踏实。等本地跑通了再考虑要不要迁移到远程共享。这个顺序不要反否则你会同时面对配置对不对和网络通不通两个问题非常折磨。3. 核心配置把 NanoBanana MCP 挂到 OpenCode 上3.1 找到 OpenCode 的配置文件OpenCode 的配置文件位置跟操作系统有关常见路径macOS / Linux~/.config/opencode/config.json或项目根目录的opencode.jsonWindows%APPDATA%\opencode\config.json如果找不到可以在 OpenCode 里执行帮助命令或者看启动日志里加载了哪个路径。我一般用这个命令快速定位# macOS / Linux ls -la ~/.config/opencode/ # Windows PowerShell dir $env:APPDATA\opencode\配置文件分全局和项目级两种。全局配置对所有项目生效适合放通用的 MCP Server项目级配置只对当前项目生效适合放项目专用的工具。NanoBanana 这种通用图像能力我建议放全局。3.2 编写 mcpServers 配置块假设 NanoBanana 提供的是 npm 包形式的 stdio Server配置大概长这样{ mcpServers: { nanobanana: { command: npx, args: [-y, nanobanana/mcp-server], env: { NANOBANANA_API_KEY: 你的密钥 } } } }逐字段解释一下别照抄完不知道在干嘛nanobanana这是你给这个 Server 起的名字OpenCode 里调用时会用到起个短好记的。command启动命令npx表示用 npm 的临时执行器。args传给命令的参数-y表示自动确认安装后面是包名。env环境变量密钥这类敏感信息放这里不要硬编码在代码里。如果是 Python 包配置会变成{ mcpServers: { nanobanana: { command: python, args: [-m, nanobanana_mcp], env: { NANOBANANA_API_KEY: 你的密钥 } } } }注意密钥不要提交到 Git。如果配置文件在项目里记得加进.gitignore。我见过有人把带密钥的配置推到公开仓库结果被人刷爆额度。3.3 环境变量的正确管理方式把密钥直接写在 JSON 里虽然能跑但不优雅也不安全。更好的做法是用环境变量引用。很多配置支持这种写法{ mcpServers: { nanobanana: { command: npx, args: [-y, nanobanana/mcp-server], env: { NANOBANANA_API_KEY: ${NANOBANANA_API_KEY} } } } }然后在 shell 的启动文件里.bashrc、.zshrc或 Windows 的环境变量设置导出export NANOBANANA_API_KEY你的密钥这样配置文件可以放心分享密钥只存在本机环境里。团队协作时每个人配自己的密钥配置文件统一非常清爽。3.4 验证配置是否生效配置写完重启 OpenCode然后查看 MCP Server 的加载状态。不同版本命令不同常见的有opencode mcp list或者直接在对话里问 OpenCode现在有哪些可用的 MCP 工具如果配置正确应该能看到 nanobanana 相关的工具列表。如果没看到先别急着改配置按这个顺序排查配置文件路径对不对用--verbose启动看日志JSON 语法有没有错用jq . config.json验证命令能不能手动跑通把 command 和 args 拼起来在终端执行密钥有没有正确传入在 Server 启动日志里看这个排查顺序是从外到内先排除低级错误再深入。我见过太多人一上来就怀疑协议不兼容结果发现是 JSON 少了个逗号。4. 实操从零跑通一次图像编辑4.1 手动启动 Server 验证连通性在把 Server 交给 OpenCode 管理之前先手动跑一次确认它本身能工作。这一步能帮你把Server 的问题和OpenCode 的问题分开。NANOBANANA_API_KEY你的密钥 npx -y nanobanana/mcp-server如果启动成功通常会看到类似Server started, listening on stdio的日志。这时候它是在等输入你可以按 CtrlC 退出。如果报错错误信息会直接告诉你缺什么——可能是密钥无效、依赖没装好、或者版本不匹配。提示手动启动时如果卡住不动可能是它在等 stdin 输入这是正常的。关键是看有没有报错而不是看它有没有退出。4.2 在 OpenCode 里发起第一次调用Server 验证通过后重启 OpenCode在对话里描述你的需求。比如帮我用 nanobanana 把 ./assets/screenshot.png 裁剪成 800x600输出到 ./assets/screenshot-cropped.pngOpenCode 会解析你的意图匹配到 nanobanana 的裁剪工具然后发起调用。第一次调用可能会慢一点因为要初始化 Server 进程。调用过程中注意观察 OpenCode 的输出。如果它显示了工具调用的参数和返回结果说明链路通了。如果它说找不到工具回到 3.4 排查。4.3 参数传递的细节图像编辑工具的参数通常包括输入路径、输出路径、操作类型、具体参数尺寸、格式、质量等。这里有几个容易出错的点路径问题相对路径是相对于 OpenCode 的工作目录不是相对于配置文件。如果你不确定用绝对路径最稳。格式支持确认 NanoBanana 支持你要的输出格式。有些工具只支持 PNG 和 JPEG你传 WebP 就会失败。尺寸约束裁剪和缩放不一样。裁剪是切掉一部分缩放是整体变形。说清楚你要哪个。我一般会先做一次最简单的操作比如格式转换确认链路通了再上复杂操作。这样出问题时变量最少。4.4 一次完整的实操记录下面是我实际跑通的一次流程供参考第一步准备一张测试图放在项目目录下cp ~/Pictures/test.png ./assets/test.png第二步在 OpenCode 里发起请求用 nanobanana 把 assets/test.png 转成 JPEG质量 85输出到 assets/test.jpg第三步观察输出。OpenCode 返回了工具调用详情包括输入参数和输出路径。检查文件ls -la assets/test.jpg file assets/test.jpgfile命令会告诉你实际格式确认转换成功。第四步如果结果不对看 Server 日志。OpenCode 一般会把 MCP Server 的 stderr 输出到日志文件路径通常在~/.local/share/opencode/logs/或类似位置。这套流程跑一遍你对整个链路的理解就立体了后面遇到问题也知道从哪查。5. 常见问题与排查技巧实录5.1 工具列表为空怎么办这是最常见的问题。OpenCode 启动了但看不到任何 nanobanana 工具。原因通常有三类现象可能原因排查方法完全没加载配置路径错误用 verbose 模式看加载了哪个文件加载了但报错命令执行失败手动跑 command args加载成功但无工具Server 未暴露工具看 Server 文档确认能力我遇到过一次配置写对了但npx因为网络问题下载包失败导致 Server 起不来。手动跑一次命令看到下载超时的报错换了镜像源就好了。5.2 调用超时或卡死图像处理本身可能耗时尤其是大图或复杂操作。如果 OpenCode 等了一会儿没反应先别急着杀进程。检查Server 进程是否还在ps aux | grep nanobanana是否有网络请求卡住远程 Server 常见图片是不是特别大超过几十 MB 的处理会慢如果确认卡死可以在配置里加超时参数如果 Server 支持或者先处理小图验证链路。5.3 密钥无效或权限不足报错信息里出现 401、403 这类状态码基本就是密钥问题。检查密钥有没有复制完整前后空格、换行密钥有没有过期账户额度是否用完密钥对应的权限是否包含你要用的功能我习惯把密钥先在一个最小的测试脚本里验证确认有效再往配置里放。这样能排除是密钥问题还是配置问题的干扰。5.4 输出文件找不到调用返回成功但文件不在预期位置。这种情况多半是路径理解不一致。解决方法是统一用绝对路径或者明确 OpenCode 的工作目录。可以在对话里先问一句当前工作目录是哪里确认后再操作。5.5 独家避坑清单这些都是我实际踩过的文档里不会写别在配置文件里写中文注释JSON 不支持注释有些解析器遇到中文会报奇怪的错。Windows 路径用双反斜杠或正斜杠C:\\Users\\...或C:/Users/...单反斜杠会被转义。Server 名字别用大写和空格有些客户端对名字有格式要求用小写加连字符最稳。升级 OpenCode 后重新验证 MCP版本升级可能改变配置格式别想当然。保留一份能跑通的最小配置出问题时用它对照快速定位是配置改动引入的问题。6. 把图像编辑真正融入开发工作流6.1 从能用到好用的差距跑通一次调用只是起点。真正提升效率是要让这个能力自然地出现在你需要它的时刻。我的做法是把常用的图像操作固化成几个话术模板需要时直接说不用每次重新描述。比如把当前目录下所有 png 转成 webp质量 80给这张图加 20px 白色边框把这张截图裁掉顶部 100px 的状态栏这些模板存在我的笔记里用的时候复制粘贴改一下路径就行。比每次从零描述快得多。6.2 和文档、CI 流程结合如果你的项目有文档目录配图是刚需。可以考虑在文档构建流程里加一步用 MCP 调用批量处理图片。虽然 MCP 本身是给 AI 客户端用的但你可以写个脚本模拟调用或者用 OpenCode 的批处理模式。更实际的做法是在写文档时直接在 OpenCode 里让 AI 帮你处理配图处理完顺手写进 Markdown。这个流程比打开图像软件→处理→保存→回到编辑器→插入顺畅太多。6.3 能力边界的清醒认知最后说点实在的。MCP 接入图像编辑适合的是轻量、高频、可描述的图像操作。如果你要做复杂的图层合成、精细的修图还是得用专业软件。别指望一个终端里的工具能替代 Photoshop那不现实。它的价值在于把那些本来要切出去做、但其实很简单的操作留在工作流里完成。省下的是切换成本不是专业能力。想清楚这一点你就不会对它有不切实际的期待也不会因为它做不了复杂修图而失望。我在实际使用中的体会是这套方案最大的收益不是省了多少时间而是保持了心流。写代码的时候思路是连贯的中间插一个图像处理不用跳出去回来还能接着写。这种连续性比单纯的时间节省更值钱。