opencode-image-mcp

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

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

功能特性

• 🎨 文生图：文字描述 → 生成图片

• 🖼️ 图生图：参考图 + 文字指令 → 风格转换/变体/编辑

• 🔄 多后端可切换：qwen-image（阿里云）/ Seedream（火山方舟）/ CogView（智谱）

• 📁 结果落盘：生成图片保存到本地 outputs/，返回 file:// 路径

• 🚫 零 base64 污染：主模型上下文只接触路径字符串

• 🔁 自动重试：429 / 5xx 指数退避重试

• 🤝 与 vision MCP 协同：生成的图可直接用 vision MCP 自检质量

Related MCP server: openrouter-image-gen-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

• 通义万相：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

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

image_list_models

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

环境变量

扩展新的生图后端

项目采用后端注册表 + 统一函数签名设计，新增一家后端只需 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