Opencode Image

给不支持生图能力的主模型（如 DeepSeek）提供"画画"能力的 MCP server。

主模型只需给出文字描述（和可选的参考图路径），本 server 调用第三方生图模型（通义万相 qwen-image / 豆包 Seedream / 智谱 CogView）生成图片，下载到本地 outputs/ 目录，返回本地文件路径——图片数据不进入主模型上下文。

功能特性

• 🎨 文生图：文字描述 → 生成图片
• 🖼️ 图生图：参考图 + 文字指令 → 风格转换/变体/编辑
• 🔄 多后端可切换：qwen-image（阿里云）/ Seedream（火山方舟）/ CogView（智谱）
• 📁 结果落盘：生成图片保存到本地 outputs/，返回 file:// 路径
• 🚫 零 base64 污染：主模型上下文只接触路径字符串
• 🔁 自动重试：429 / 5xx 指数退避重试
• 🤝 与 vision MCP 协同：生成的图可直接用 vision MCP 自检质量

原理

你在对话框输入文字描述（+可选参考图路径）
  ↓
主模型调用 image_generate 工具
  ↓
本 server 调用生图后端（qwen-image / Seedream）
  ↓
生成图片 → 下载到 outputs/ 目录
  ↓
返回 {"images": [{"path": "C:/.../outputs/xxx.png"}], ...}
  ↓
主模型把路径展示给你；配合 vision MCP 可回读检查生成质量

图片字节全程不进入主模型上下文——只传路径字符串。

目录结构

opencode-image-mcp/
├── server.py              # MCP server 主程序（stdio 传输）
├── requirements.txt       # Python 依赖
├── .env.example           # 环境变量模板
├── .gitignore
├── LICENSE                # MIT
└── outputs/               # 生成图片输出目录（自动创建）

安装

环境要求

• Python >= 3.10
• opencode
• 至少一个生图后端的 API key

安装步骤

git clone https://github.com/Jsliu28/opencode-image-mcp.git
cd opencode-image-mcp

python -m venv .venv
# Windows:
.\.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt

cp .env.example .env   # 编辑 .env 填入 API key

配置 API key

标识	名称	API key 环境变量	默认模型
wanx	通义万相 qwen-image	DASHSCOPE_API_KEY	qwen-image-3.0-pro
seedream	豆包 Seedream	ARK_API_KEY	dola-seedream-5-0-pro-260628
zhipu	智谱 CogView	ZHIPU_API_KEY	cogview-4

• 通义万相：https://bailian.console.aliyun.com/（与 vision MCP 共用 key）
• 火山方舟：https://console.volcengine.com/ark
• 智谱：https://open.bigmodel.cn/

配置到 opencode

编辑 ~/.config/opencode/opencode.json：

{
  "mcp": {
    "image": {
      "type": "local",
      "command": ["python", "C:/你的路径/opencode-image-mcp/server.py"],
      "enabled": true,
      "environment": {
        "IMAGE_DEFAULT_PROVIDER": "wanx"
      }
    }
  }
}

python 不在 PATH 时用虚拟环境解释器绝对路径。API key 在 .env 中自动读取。

使用示例

你：画一只戴帽子的猫，卡通风格
你：画一张 16:9 的风景壁纸
你：把这张图 C:/Users/me/photo.png 变成水彩画风格
你：参考 https://example.com/ref.jpg 生成同风格的海报

工具说明

image_generate

文生图 + 图生图（一个工具）。参数：

参数	类型	必填	说明
prompt	string	✅	图片描述（或对参考图的编辑指令）
input_image_path	string	❌	参考图路径/URL，提供后为图生图
size	string	❌	尺寸。wanx: 1024*1024 / 720*1280 / 1280*720；seedream: 1K / 2K
provider	string	❌	wanx / seedream / zhipu，覆盖默认后端
model	string	❌	具体模型名（如 qwen-image-edit-max）

image_list_models

列出可用生图后端、模型、配置状态。

环境变量

变量	默认值	说明
IMAGE_DEFAULT_PROVIDER	wanx	默认后端
DASHSCOPE_API_KEY	-	通义万相 key
ARK_API_KEY	-	豆包 Seedream key
ZHIPU_API_KEY	-	智谱 CogView key
IMAGE_OUTPUT_DIR	outputs	输出目录
IMAGE_MAX_RETRIES	2	失败重试次数
IMAGE_RETRY_BASE_DELAY	1.0	重试基础等待（秒）

扩展新的生图后端

项目采用后端注册表 + 统一函数签名设计，新增一家后端只需 3 步（在 server.py 中）：

1. 注册配置：在 PROVIDERS 字典中添加一个条目（仿照现有条目），指定：

   • api_key_env：API key 的环境变量名
   • task_submit_url：生图接口地址
   • models / default_model：文生图模型
   • i2i_models / i2i_default_model：图生图模型（如支持）
   • sizes：可用尺寸列表

2. 实现生成函数：编写 _xxx_generate(prompt, model, size, input_image_data, input_image_mime, input_image_url)，保持与其他后端相同的参数签名，内部实现该后端的请求构造与响应解析，最后返回本地文件路径列表（List[Path]）。

3. 注册调度：在 _generate 调度函数中添加该 provider 的分支分发。

完成后即可通过 provider 参数使用新后端，无需改动 MCP 工具层。参考实现：_wanx_generate / _seedream_generate / _zhipu_generate。

常见问题

Q: 报"后端未配置"？ A: 检查 .env 中对应 key，image_list_models 可查看状态。

Q: 参考图无法读取？ A: 参考图需为本地绝对路径或可公开访问的 URL，最大 20MB。

Q: 生成太慢？ A: qwen-image 同步接口通常 10-30 秒；限流（429）会自动重试。

Q: 生成的图在哪？ A: 返回的 path 即本地文件位置，默认在项目 outputs/ 目录。

Q: 能接其他生图模型吗？ A: 可以。参考"扩展新的生图后端"章节，在 server.py 中按 3 步添加即可（注册表 + 函数 + 调度）。

License

MIT