使用说明

mcp图像生成器

MCP服务器 本地图像生成 使用稳定扩散.cpp 通过扩散rs.完全在您的计算机上运行-没有API密钥，没有云，没有数据离开您的计算机。

适用于任何MCP客户端： 克劳德代码CLIClaude Desktop或任何其他MCP兼容工具。

它做什么

为您的AI助手提供三个工具：

工具	说明
`generate_image`	从文本提示生成图像。返回文件路径
`download_model`	从HuggingFace下载模型
`list_models`	列出可用（下载）型号

支持的架构： 通量。2, 通量。1, SDXL，以及GGUF/safetensors格式的兼容模型。

特性

LoRA支持 --申请 .safetensors 具有可配置强度的LoRA适配器
多个模型 --通过以下方式在模型之间切换 models.json 配置
自动下载 --首次使用时从HuggingFace下载模型
CUDA加速 --可选，通过功能标志
拥抱脸令牌 --支持门控型号（FLUX.2-dev等）
CPU卸载 --在有限的VRAM上运行大型模型
闪光注意力和VAE瓷砖 --每个模型的优化标志

快速开始

1.建造

git clone https://github.com/aitherlab-dev/mcp-image-gen.git
cd mcp-image-gen
cargo build --release

在CUDA的支持下：

cargo build --release --features cuda

二进制文件将位于 target/release/mcp-image-gen.

（可选）将其复制到您的 $PATH:

cp target/release/mcp-image-gen ~/.local/bin/

2.添加到克劳德代码

编辑 ~/.claude.json （或创建它）并将服务器添加到 mcpServers:

{
  "mcpServers": {
    "image-gen": {
      "command": "/home/you/.local/bin/mcp-image-gen",
      "env": {}
    }
  }
}

就是这样。服务器将使用默认路径，并在首次使用时自动下载默认模型。

自定义路径（可选）

如果要控制模型和图像的存储位置：

{
  "mcpServers": {
    "image-gen": {
      "command": "/home/you/.local/bin/mcp-image-gen",
      "env": {
        "MCP_IMAGE_GEN_MODELS_PATH": "/home/you/ai-models",
        "MCP_IMAGE_GEN_IMAGES_PATH": "/home/you/ai-images",
        "HF_TOKEN": "hf_your_token_here"
      }
    }
  }
}

克劳德桌面版

相同的配置格式--添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "image-gen": {
      "command": "/home/you/.local/bin/mcp-image-gen",
      "env": {}
    }
  }
}

3.使用它

启动Claude Code并要求它生成图像：

> Generate an image of a sunset over mountains

首次运行时，模型将自动下载（默认FLUX.2 Klein 4B约4.4 GB）。后续运行使用缓存的模型。

服务器返回生成图像的文件路径。在Claude Code CLI中，您将看到类似以下内容：

Image saved: /home/you/.local/share/mcp-image-gen/images/20250326_142030_abc12345.png

配置

设置文件

~/.config/mcp-image-gen/settings.json

{
  "modelsPath": "/home/you/.local/share/mcp-image-gen/models",
  "imagesPath": "/home/you/.local/share/mcp-image-gen/images",
  "selectedModel": "flux2-klein-4b",
  "width": 1024,
  "height": 1024,
  "steps": 20
}

首次运行时自动创建默认值。您可以手动编辑它，也可以让服务器管理它。

环境变量

通过环境覆盖任何配置值：

变量	描述	默认值
`MCP_IMAGE_GEN_MODELS_PATH`	在哪里存储/缓存下载的模型	`~/.local/share/mcp-image-gen/models`
`MCP_IMAGE_GEN_IMAGES_PATH`	生成的图像保存在哪里	`~/.local/share/mcp-image-gen/images`
`MCP_IMAGE_GEN_SELECTED_MODEL`	默认型号ID	`flux2-klein-4b`
`HF_TOKEN`	用于封闭模型的HuggingFace API令牌	-
`RUST_LOG`	日志级别（例如。 `mcp_image_gen=debug`)	`mcp_image_gen=info`

型号配置

模型定义见 ~/.config/mcp-image-gen/models.json。首次运行时使用默认模型自动创建。

每个模型条目都为所有组件指定了HuggingFace存储库/文件：

[
  {
    "id": "flux2-klein-4b",
    "name": "FLUX.2 Klein 4B",
    "diffusion": { "repo": "leejet/FLUX.2-klein-4B-GGUF", "file": "flux-2-klein-4b-Q8_0.gguf" },
    "vae": { "repo": "black-forest-labs/FLUX.2-dev", "file": "vae/diffusion_pytorch_model.safetensors" },
    "llm": { "repo": "unsloth/Qwen3-4B-GGUF", "file": "Qwen3-4B-Q8_0.gguf" },
    "steps": 4,
    "cfg_scale": 1.0,
    "width": 1024,
    "height": 1024,
    "offload_cpu": true,
    "flash_attn": true,
    "vae_tiling": true
  }
]

添加自定义模型

将条目添加到 models.json 使用HuggingFace仓库和每个组件的文件名：

字段	必填	描述
`id`	yes	唯一标识符
`name`	yes	显示名称
`diffusion`	是	主模型文件（GGUF或safetensor）-- `{"repo": "...", "file": "..."}`
`vae`	无	VAE解码器
`llm`	无	文本编码器（FLUX型号）
`clip_l`	无	CLIP-L文本编码器（SDXL）
`t5xxl`	无	T5-XXL编码器（FLUX）
`single_file`	没有	`true` 对于单文件模型（SDXL安全张量）
`steps`	no	默认推理步骤（默认值：4）
`cfg_scale`	否	无分类器引导量表（默认值：1.0）
`width` / `height`	否	默认分辨率（默认值：1024）
`offload_cpu`	no	将模型参数卸载到CPU（保存VRAM）
`flash_attn`	否	启用闪光注意力
`vae_tiling`	否	启用VAE平铺（为大图像保存VRAM）

LoRA适配器

将LoRA字段添加到中的任何模型条目 models.json:

{
  "id": "flux2-klein-4b",
  "lora": "/home/you/loras/anime-style.safetensors",
  "lora_strength": 0.8,
  "lora_enabled": true
}

字段	描述
`lora`	通往a的完整路径 `.safetensors` LoRA文件
`lora_strength`	乘数，0.0–2.0（默认值：1.0）
`lora_enabled`	在不删除路径的情况下打开/关闭（默认值：true）

默认模型

FLUX.2克莱因4B （Q8_0 GGUF）--总计约4.4 GB：

扩散模型： leejet/FLUX.2-klein-4B-GGUF
VAE： black-forest-labs/FLUX.2-dev
文本编码器： unsloth/Qwen3-4B-GGUF

速度快（4步），1024×1024的质量好。在8 GB VRAM上运行，CPU卸载。

需求

锈蚀1.75+
CMake （用于建立稳定的扩散。cpp）
CUDA工具包 （可选，用于GPU加速）
默认型号约4.4 GB磁盘空间
建议使用8 GB+VRAM（CPU卸载更少）

Linux（Ubuntu/Debian）

sudo apt install cmake build-essential

Linux（Arch）

sudo pacman -S cmake base-devel

macOS

brew install cmake

运作原理

Claude Code ←→ mcp-image-gen (stdio, JSON-RPC) ←→ diffusion-rs ←→ stable-diffusion.cpp

服务器通过stdin/stdout使用 MCP协议（基于stdio的JSON-RPC）。映像生成在单独的线程中运行，以不阻塞协议处理程序。

生成的图像保存到磁盘，文件路径以文本形式返回。您的MCP客户端（Claude Code、Claude Desktop等）接收路径，并可以显示或引用图像。

故障排除

“生成HF API失败” --检查你的互联网连接。模型在首次使用时从HuggingFace下载。

“此模型需要HuggingFace令牌” --set HF_TOKEN 在您的环境或 ~/.claude.json。有些型号（如FLUX.2-dev）需要先在huggingface.co上接受许可证。

VRAM不足 --启用 offload_cpu: true 和 vae_tiling: true 在您的模型配置中。或者使用较小的型号。

缓慢的一代 --构建与 --features cuda 用于GPU加速。没有它，推理就在CPU上运行。

日志 --stderr输出将进入Claude Code的MCP服务器日志。集 RUST_LOG=mcp_image_gen=debug 用于详细输出。

许可证

麻省理工学院

学分

由...建造 aitherlab.部分等待流项目。

技术支持：

扩散rs --稳定扩散.cpp的Rust绑定
稳定扩散.cpp --C++推理引擎