MCP 服务器

opencode-image-mcp

MCP server that gives non-image-capable models like DeepSeek the ability to generate images using backends such as Qwen-Image, Seedream, and CogView, saving them locally and returning file paths instead of base64 data.

README

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 自检质量

原理

你在对话框输入文字描述（+可选参考图路径）
  ↓
主模型调用 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: `10241024` / `7201280` / `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 中）：

注册配置：在 PROVIDERS 字典中添加一个条目（仿照现有条目），指定：
- api_key_env：API key 的环境变量名
- task_submit_url：生图接口地址
- models / default_model：文生图模型
- i2i_models / i2i_default_model：图生图模型（如支持）
- sizes：可用尺寸列表
实现生成函数：编写 _xxx_generate(prompt, model, size, input_image_data, input_image_mime, input_image_url)，保持与其他后端相同的参数签名，内部实现该后端的请求构造与响应解析，最后返回本地文件路径列表（List[Path]）。
注册调度：在 _generate 调度函数中添加该 provider 的分支分发。