🖼️ image-for-reasonix

MCP Server — 为不支持原生生图能力的大模型补齐图像生成能力。

兼容任何 OpenAI API 格式的图像生成提供商，支持多模式输出（URL/Base64/本地保存）、图生图（img2img），一套代码适配本地和远程部署。

---

🔥 一行命令

uvx --from git+https://github.com/Doctor-Pan-code/image-for-Reasonix image-for-reasonix

---

📋 环境变量速查表

变量名	说明	必填	示例值
IMAGE_API_KEY	提供商 API Key	✅ 必填	sk-xxx...
IMAGE_BASE_URL	API 地址（需以 /v1 结尾）	✅ 必填	https://api.siliconflow.cn/v1
IMAGE_MODEL	默认生图模型名	✅ 必填	black-forest-labs/FLUX.1-dev
IMAGE_OUTPUT_DIR	本地保存目录	❌ 可选	./output

⚠️ 三个核心变量都必须配置，不设默认值，由你自由选择提供商。

快速开始

# 硅基流动示例
export IMAGE_API_KEY=sk-你的API密钥
export IMAGE_BASE_URL=https://api.siliconflow.cn/v1
export IMAGE_MODEL=black-forest-labs/FLUX.1-dev
uvx --from git+https://github.com/Doctor-Pan-code/image-for-Reasonix image-for-reasonix

---

🛠 提供的 Tool

Tool	功能	用途
generate_image	文本生成图片	🎯 核心 tool，根据 prompt 生成一张或多张图
list_models	查看配置和提供商参考	📋 查看当前配置及常见提供商信息
generate_image_with_reference	图生图 (img2img)	🎨 基于参考图生成新图（需 API 支持）

generate_image

生成图片的核心工具，支持多模式输出。

参数：

参数	类型	必填	默认	说明
prompt	string	✅	—	图片描述，越详细效果越好
model	string	❌	IMAGE_MODEL	模型名称
size	string	❌	1024x1024	图片尺寸
n	int	❌	1	生成数量（最大 4）
output_mode	string	❌	url	输出模式: url / b64 / local / all
output_dir	string	❌	环境变量	本地保存目录（local/all 模式）

使用示例：

生成一张「夕阳下的雪山湖泊，写实风格」的图片
→ generate_image(prompt="夕阳下的雪山湖泊，写实风格，高分辨率，金色阳光洒在雪山上")

list_models

查看当前配置信息及常见图像生成提供商参考。

→ list_models()

generate_image_with_reference

基于参考图片进行图生图（需要 API 提供商和模型支持 img2img）。

参数：

参数	类型	必填	默认	说明
prompt	string	✅	—	新图片描述
reference_url	string	✅	—	参考图 URL
strength	float	❌	0.8	参考图影响强度 (0~1)
model	string	❌	默认模型	模型名称
size	string	❌	1024x1024	图片尺寸
output_mode	string	❌	url	输出模式

---

🔌 常见提供商参考配置

以下是一些常见的图像生成 API 提供商，供配置时参考（代码不做任何硬编码预设）：

1. 硅基流动 (SiliconFlow)

IMAGE_API_KEY=sk-你的硅基流动Key
IMAGE_BASE_URL=https://api.siliconflow.cn/v1
IMAGE_MODEL=black-forest-labs/FLUX.1-dev

可用模型	说明
black-forest-labs/FLUX.1-dev	🌟 推荐，性价比平衡
black-forest-labs/FLUX.1-schnell	速度更快，质量略低
stabilityai/stable-diffusion-3-5-large	高画质，写实风格
stabilityai/sd3.5-large-turbo	SD3.5 快速版

官网：https://cloud.siliconflow.cn

2. OpenAI

IMAGE_API_KEY=sk-你的OpenAI Key
IMAGE_BASE_URL=https://api.openai.com/v1
IMAGE_MODEL=dall-e-3

可用模型	说明
dall-e-3	最新版，质量高
dall-e-2	旧版，价格低

注意：OpenAI 不支持图生图 (img2img)

3. 阿里通义万相 (DashScope)

IMAGE_API_KEY=sk-你的DashScope Key
IMAGE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
IMAGE_MODEL=wanx2.1-t2i-turbo

可用模型	说明
wanx2.1-t2i-turbo	快速生成
wanx2.1-t2i-plus	高质量生成

官网：https://dashscope.aliyun.com

---

🖥 多客户端配置

Reasonix

编辑 %APPDATA%/reasonix/config.toml：

[[plugins]]
name    = "image-for-reasonix"
command = "uvx"
args    = ["--from", "git+https://github.com/Doctor-Pan-code/image-for-Reasonix", "image-for-reasonix"]
env     = {
    IMAGE_API_KEY = "你的 API Key",
    IMAGE_BASE_URL = "https://api.siliconflow.cn/v1",
    IMAGE_MODEL = "black-forest-labs/FLUX.1-dev"
}

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "image-for-reasonix": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Doctor-Pan-code/image-for-Reasonix", "image-for-reasonix"],
      "env": {
        "IMAGE_API_KEY": "你的 API Key",
        "IMAGE_BASE_URL": "https://api.siliconflow.cn/v1",
        "IMAGE_MODEL": "black-forest-labs/FLUX.1-dev"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "image-for-reasonix": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Doctor-Pan-code/image-for-Reasonix", "image-for-reasonix"],
      "env": {
        "IMAGE_API_KEY": "你的 API Key",
        "IMAGE_BASE_URL": "https://api.siliconflow.cn/v1",
        "IMAGE_MODEL": "black-forest-labs/FLUX.1-dev"
      }
    }
  }
}

---

🧪 本地测试

使用 MCP Inspector

# 从 GitHub 安装测试
npx @modelcontextprotocol/inspector uvx --from git+https://github.com/Doctor-Pan-code/image-for-Reasonix image-for-reasonix

# 本地开发测试
npx @modelcontextprotocol/inspector uv run server.py

启动后在浏览器打开 http://localhost:5173，可以：

1. ✅ 查看工具列表 — 验证 3 个 tool 是否被发现
2. ✅ 调用 list_models — 查看当前配置和常见提供商参考
3. ✅ 调用 generate_image — 传入 prompt 测试生图效果
4. ✅ 查看错误日志 — 定位问题

本地直接运行

# 安装依赖
pip install mcp python-dotenv

# 运行（stdio 模式）
python server.py

# 运行（SSE 模式，远程部署）
python server.py --transport sse --port 9877

---

🚀 部署到魔搭（ModelScope Hosted）

1. 将本仓库推送到 GitHub
2. 在魔搭平台创建 MCP 服务，选择 sse 传输方式
3. 配置环境变量 IMAGE_API_KEY、IMAGE_BASE_URL、IMAGE_MODEL
4. 部署后获得 SSE URL，配置到客户端

---

🏗 项目结构

image-for-reasonix/
├── server.py           # MCP Server 主入口（所有 tool 定义）
├── pyproject.toml      # 依赖管理 + uvx 入口点配置
├── README.md           # 本文档
├── .env.example        # 环境变量模板
└── .gitignore          # Git 忽略规则

---

🔐 安全提示

• 不要提交 .env 文件到 Git，它包含 API Key
• 使用 .env.example 作为模板，填写占位符
• 所有用户输入的 prompt 经过长度限制，防止滥用
• 本地保存模式下，图片存储在 output_dir 目录中

---

📝 许可证

MIT