Image Generation MCP Server

Image Generation MCP

基于 FastMCP 构建的多提供商图像生成 MCP 服务。可通过 Claude Desktop、Claude Code 或任何 MCP 客户端，使用 OpenAI、Google Gemini、Stable Diffusion（SD WebUI）或零成本占位提供商生成图像。

文档 | 配置向导 | PyPI | Docker

功能特性

• 多提供商：OpenAI（gpt-image-2、gpt-image-1.5、dall-e-3）、Google Gemini（gemini-3.1-flash-image、gemini-3-pro-image、gemini-3.1-flash-lite-image）、SD WebUI（Stable Diffusion / Forge / reForge），以及用于测试的零成本占位提供商。
• 按模型提供风格元数据：每个模型都带有 style_profile（优势、提示词语法、生命周期）；list_providers 包含用于标记弃用模型的顶层 warnings 数组。请参阅模型目录。
• 基于关键词自动选择：provider="auto" 会根据提示词内容路由（文本/徽标 → OpenAI，照片级真实感/动漫 → SD WebUI，草稿 → 占位提供商）。
• CDN 风格的图像转换：image://{id}/view?format=webp&width=512&crop_x=... 可按需调整大小、重新编码和裁剪，无需重新生成。
• 混合式后台任务：耗时较长的 SD 生成任务通过 task=True 运行（可轮询状态）；较短的 OpenAI 调用则在前台流式传输进度。
• MCP Apps 图库 + 查看器：为支持 app: 资源的客户端提供交互式 UI（浏览生成的图像、编辑 / 裁剪 / 旋转）。
• 生产环境部署：Docker（多架构）、带有强化版 systemd 的 .deb/.rpm、OIDC + bearer 身份验证，以及支持 HTTP 会话恢复的持久化 EventStore。

你可以用它做什么

将此服务挂载到 MCP 客户端后，你可以提出以下请求：

• “在一张旧橡木桌上生成一张咖啡杯产品照片，宽高比为 16:9，不要文字。” 将请求路由到 gpt-image-1.5，生成能处理排版的写实照片。
• “创作三张赛博朋克风格的黄昏小巷概念艺术变体。” 使用 provider="sd_webui" 调用 generate_image，并搭配 dreamshaperXL 之类的风格化检查点。
• “将这张图片裁剪为以主体为中心的 1:1 正方形，并调整至 512px。” 使用 image://{id}/view?width=512&height=512&crop_x=... 资源变换。
• “显示我最近生成的图片。” 通过 image://list 资源和 MCP Apps 图库查看器浏览图库。
• “将此风格保存为‘cyberpunk-night’，以便我在以后的请求中使用。” 使用风格库，其中的 Markdown 简介会由大模型按提供方进行解读。
• “将我上一张照片的背景替换为日落天空。” 使用 transform_image，并将图库中的 image_id 作为参考（通过 Gemini 进行图生图）。

安装

从 PyPI 安装

pip install image-generation-mcp

如果你通过 pyproject.toml 中的 PROJECT-EXTRAS-START / PROJECT-EXTRAS-END 标记添加了可选附加项，请在下方说明：

附加项	包含内容	适用场景
mcp	fastmcp[tasks]>=3.0,<4	支持后台任务（task=True），长时间运行的 SD 生成任务必需。
openai	openai>=1.0	启用 OpenAI 提供方。
google-genai	google-genai>=1.0	启用 Gemini 提供方。
all	fastmcp[tasks] + openai + google-genai	包含除 SD WebUI 外的所有内容（它仅使用 HTTP，无需额外项）。

示例：pip install image-generation-mcp[all]。

从源代码安装

git clone https://github.com/pvliesdonk/image-generation-mcp.git
cd image-generation-mcp
uv sync --all-extras --all-groups

Docker

docker pull ghcr.io/pvliesdonk/image-generation-mcp:latest

若要运行最新合并代码而不是最新发行版，请使用滚动更新的 edge 标签。每次合并到 main 时都会重新构建，且不对应任何特定版本。完整标签列表请参阅 镜像标签。

docker pull ghcr.io/pvliesdonk/image-generation-mcp:edge

仓库根目录附带一个 compose.yml，可作为起点。将 .env.example 复制为 .env，进行编辑，然后运行 docker compose up -d。

如需连接远程 Python 调试器（仅用于开发；该协议未进行身份验证），请参阅远程调试。

Linux 软件包（.deb / .rpm）

从 GitHub Releases 页面下载 .deb 或 .rpm 软件包。两者都会安装经过安全加固的 systemd 单元；环境配置从 /etc/image-generation-mcp/env 读取（可从随包提供的 /etc/image-generation-mcp/env.example 复制）。

Claude Desktop（.mcpb bundle）

从 GitHub Releases 页面下载 .mcpb bundle，然后双击安装，或运行：

mcpb install image-generation-mcp-<version>.mcpb

Claude Desktop 会通过图形界面向导提示你填写必需的环境变量，无需手动编辑 JSON。

有关 Claude Desktop 的手动配置和设置选项，请参阅 Claude Desktop 部署。

发布渠道

制品通过三个渠道发布。每一行都准确列出了该渠道发布的内容。

渠道	版本标识	制品
edge（滚动发布）	无；以提交作为标识	Docker 镜像 :edge，每次合并到 main 时都会重新构建；.mcpb 包，作为 mcpb-bundle-edge 工作流制品；Claude Code 插件 .zip，作为 plugin-zip-edge 制品；滚动的 unstable 文档版本。不会留下 git 标签、GitHub 发布版本或 PyPI 条目。
预发布版本	vX.Y.Z-rc.N，在其发布拉取请求中计算并审核	PyPI（作为预发布版本 X.Y.ZrcN）；附带 wheel、sdist、.deb/.rpm 包、.mcpb 包、插件 .zip 和 SBOM 的 GitHub 发布版本；Docker 镜像使用不可变的 vX.Y.Z-rc.N 标签，以及按版本顺序更新的滚动 rc 标签。跳过插件市场、MCP 注册表和文档部署。
稳定版	vX.Y.Z	全部内容：PyPI、Docker（版本标签，以及按版本顺序更新的 latest / vX / vX.Y）、.deb/.rpm、GitHub 发布资产（wheel、sdist、.mcpb 包、插件 .zip、SBOM）、插件市场和 MCP 注册表条目（当此版本是最新稳定版时），以及带有按版本顺序更新的 latest 别名的版本化文档。

预发布版本会发布到 PyPI，以便安装候选版本的 .mcpb 包：该包指向 PyPI，而不包含代码。普通安装程序不会看到这些版本，因为除非依赖项明确指定预发布版本，或传入 --pre，否则 PEP 440 解析器会跳过预发布版本。使用 pip install image-generation-mcp==X.Y.ZrcN 按名称请求候选版本。PyPI 使用 PEP 440 规范格式，而标签使用 SemVer。滚动指针会按版本顺序更新，因此，从旧版 release/X.Y 分支切出的补丁版本不会让 latest 风格的标签回退到较旧内容，而已发布版本的候选版本也不会移动 rc。完整说明请参阅发布流程。

快速开始

image-generation-mcp serve                                # stdio transport
image-generation-mcp serve --transport http --port 8000   # streamable HTTP

如需在库中使用（嵌入领域逻辑而不使用 MCP 传输），请直接从 image_generation_mcp 包导入。入口点请参阅 src/image_generation_mcp/ 下的项目领域模块。

服务信息

服务通过 fastmcp_pvl_core.register_server_info_tool 注册内置的 get_server_info 工具，以便运维人员通过一次 MCP 调用确认已部署的版本。默认响应包含 server_name、server_version 和 core_version。与远程上游通信的服务会在 src/image_generation_mcp/server.py 的 DOMAIN-UPSTREAM-START / DOMAIN-UPSTREAM-END 哨兵标记之间接入上游版本报告；接入模式请参阅 CLAUDE.md。

配置

所有基于 fastmcp-pvl-core 的服务共用的核心环境变量：

变量	默认值	描述
IMAGE_GENERATION_MCP_KV_STORE_URL	file:///data/state	需要状态的所有 pvl-core 子系统共用的持久状态后端 URL。memory:// 是进程内存储，重启后会丢失；file:///path 会在单台服务上持久保存；redis://、dynamodb:// 和 mongodb:// 分别需要对应的额外依赖。未设置时，默认使用 file:///data/state（Docker 镜像挂载的卷目录），如果主机上该目录不可用，则默认使用 memory://，并发出警告。
FASTMCP_LOG_LEVEL	INFO	FastMCP 内部组件和应用日志记录器的日志级别（DEBUG / INFO / WARNING / ERROR / CRITICAL）。-v CLI 标志会将其覆盖为 DEBUG。
FASTMCP_ENABLE_RICH_LOGGING	true	设为 false 可输出纯文本或结构化 JSON 日志。

领域专用变量见下文的领域配置。

身份验证

调用方使用 bearer 令牌或 OIDC 进行身份验证（二者互斥）。有关设置、映射多主体令牌、OIDC 和故障排除的信息，请参阅身份验证指南。

脚手架生成后的检查清单

运行 copier copy 和 gh repo create --push 后：

1. 填写 DOMAIN 区块（本 README 和 CLAUDE.md 中每个带有 DOMAIN 哨兵注释的部分）。GENERATED-ENV-TABLE-* 区域不是 DOMAIN 区块；它们由配置生成器管理，并会在每次运行时重写。
2. 配置 GitHub 密钥（见下文）。
3. 安装开发和文档工具：uv sync --all-extras --all-groups。
4. 安装 pre-commit 钩子：uv run pre-commit install。
5. 在本地运行检查门禁：uv run pytest -x -q && uv run ruff check --fix . && uv run ruff format . && uv run mypy src/ tests/。
6. 推送首次提交。CI 应当通过。

GitHub 密钥

CI 工作流会引用三个仓库密钥。通过 Settings → Secrets and variables → Actions 配置，或使用 gh secret set：

密钥	使用方	生成方式
RELEASE_TOKEN	release-prepare.yml、release.yml、release-notes.yml、copier-update.yml、renovate.yml、bootstrap.yml	在 https://github.com/settings/personal-access-tokens/new 创建细粒度 PAT，并授予 contents: write、pull_requests: write 和 administration: write 权限（bootstrap 会应用仓库规则集并启用自动合并）。必须归属于仓库管理员：已提供的规则集授予管理员角色绕过权限，而且 knope 在发布拉取请求合并后创建的发布标签和 GitHub release 也依赖此权限（该令牌创建的拉取请求也需要此权限才能运行 CI）。权限范围限定为此仓库。
CODECOV_TOKEN	ci.yml	访问 https://codecov.io：使用 GitHub 登录并添加仓库。上传令牌位于其设置页面。
CLAUDE_CODE_OAUTH_TOKEN	claude.yml、claude-code-review.yml、release-notes.yml	在本地运行 claude setup-token，然后粘贴结果。

gh secret set RELEASE_TOKEN
gh secret set CODECOV_TOKEN
gh secret set CLAUDE_CODE_OAUTH_TOKEN

依赖更新由 Renovate（renovate.yml）处理，并复用 RELEASE_TOKEN。它会维护 uv.lock，并在 CI Success 检查通过后自动合并 补丁版和次要版本更新；首次推送时，bootstrap.yml 会启用自动合并并应用 仓库规则集（.github/rulesets/）。各分支的保护策略和绕过模式请参阅 仓库保护。GitHub Actions 会在 copier 模板中更新，并通过 copier update 引入，而不是逐个仓库更新。

GITHUB_TOKEN 会自动提供；无需操作。

本地开发

PR 检查门禁（与 CI 一致）：

uv run pytest -x -q                                  # tests
uv run ruff check --fix . && uv run ruff format .    # lint + format
uv run mypy src/ tests/                              # type-check

Pre-commit 会在每次提交时运行部分检查门禁；详情请参阅 .pre-commit-config.yaml，或查看 CLAUDE.md 了解完整的 PR 硬性验收门禁。

故障排除

移动脚手架生成的项目

uv sync 会创建 .venv/bin/* 脚本，其中包含指向虚拟环境 Python 的绝对 shebang。如果在脚手架生成后移动仓库（mv /old/path /new/path），uv run pytest 会因 ModuleNotFoundError: No module named 'fastmcp' 而失败，因为过时的 shebang 会指向与虚拟环境的 site-packages 不同的解释器。

解决方法：

rm -rf .venv
uv sync --all-extras --all-groups

uv run python -m pytest 也可作为一次性解决方法（绕过过时的入口脚本 shim）。

copier update 后刷新 uv.lock

当 copier update 引入新依赖（例如在 pyproject.toml.jinja 中新增 extra）时，CI 安装步骤会运行 uv sync --locked，而过时的锁文件会导致该步骤失败。在本地运行 uv lock，并在接受 copier 更新 PR 时一并提交刷新的 uv.lock。

CI 使用 --locked 安装（review 工作流使用 --frozen），确保没有任何任务会在自身工作区重写 uv.lock：重新生成锁文件的任务会掩盖它刚修复的偏差，而工作区变脏会导致同一任务后续的 git checkout 失败。锁文件偏差会显示为带有明确提示的安装步骤失败，而不是悄无声息地修改文件。

链接

• 文档
• llms.txt
• FastMCP
• fastmcp-pvl-core

域配置

域环境变量使用 IMAGE_GENERATION_MCP_ 前缀：

变量	默认值	必需	描述
IMAGE_GENERATION_MCP_A1111_HOST	（无）	否	已弃用的 IMAGE_GENERATION_MCP_SD_WEBUI_HOST 别名；使用时会记录警告。
IMAGE_GENERATION_MCP_A1111_MODEL	（无）	否	已弃用的 IMAGE_GENERATION_MCP_SD_WEBUI_MODEL 别名；使用时会记录警告。
IMAGE_GENERATION_MCP_READ_ONLY	true	否	为 true 时，带有写入标记的工具（图像生成、变换、上传）对客户端隐藏。设为 false 可启用这些工具。
IMAGE_GENERATION_MCP_SCRATCH_DIR	~/.image-generation-mcp/images	否	保存生成图像的目录。首次使用时自动创建。
IMAGE_GENERATION_MCP_OPENAI_API_KEY	（无）	否	OpenAI API 密钥。设置后启用 OpenAI 提供方（gpt-image-2、gpt-image-1.5、dall-e-3）。
IMAGE_GENERATION_MCP_GOOGLE_API_KEY	（无）	否	Google API 密钥。设置后启用 Gemini 提供方（gemini-3.1-flash-image 等）。可在 https://aistudio.google.com/apikey 获取密钥。
IMAGE_GENERATION_MCP_SD_WEBUI_HOST	（无）	否	SD WebUI 基础 URL（例如 http://localhost:7860）。设置后启用 SD WebUI 提供方。兼容 AUTOMATIC1111、Forge、reForge 和 Forge-neo。
IMAGE_GENERATION_MCP_SD_WEBUI_MODEL	（无）	否	SD WebUI 检查点名称，用于针对模型的预设检测（SD 1.5 / SDXL / Lightning）和检查点覆盖。未设置时使用实例当前模型。
IMAGE_GENERATION_MCP_DEFAULT_PROVIDER	auto	否	未触发关键词自动选择时使用的提供方：auto、openai、gemini、sd_webui 或 placeholder。auto 会选择第一个已配置的提供方。
IMAGE_GENERATION_MCP_TRANSFORM_CACHE_SIZE	64	否	保存在内存中的变换后图像结果（调整大小、裁剪、转换）的最大数量。设为 0 可禁用缓存。
IMAGE_GENERATION_MCP_PAID_PROVIDERS	openai	否	需要付费的提供方名称，以逗号分隔；使用这些提供方前，generate_image 会请求确认（客户端征询）。值为空时回退到此默认值；若要禁用确认，请设置一个不包含任何提供方名称的值（例如 none）。
IMAGE_GENERATION_MCP_STYLES_DIR	~/.image-generation-mcp/styles	否	样式预设文件目录（带 YAML front matter 的 Markdown 文件）。目录不存在时自动创建。
IMAGE_GENERATION_MCP_ALLOW_LOCAL_FILE_INPUT	false	否	允许从本地文件系统路径读取输入图像。默认关闭：仅接受 URL 和上传的图像。
IMAGE_GENERATION_MCP_MAX_INPUT_IMAGE_BYTES	20971520	否	接受的输入图像最大尺寸（字节）。
IMAGE_GENERATION_MCP_FETCH_TIMEOUT_S	30.0	否	获取远程图像 URL（fetch_image 和 URL 输入）时的 HTTP 超时时间（秒）。
IMAGE_GENERATION_MCP_TRANSFER_TTL_DEFAULT_S	3600.0	否	调用方未请求明确 TTL 时，链接的有效期（秒）。
IMAGE_GENERATION_MCP_TRANSFER_TTL_MAX_S	86400.0	否	调用方请求的链接 TTL 上限（秒）；超过时将限制为此值。
IMAGE_GENERATION_MCP_TRANSFER_GRACE_TTL_S	60.0	否	成功后的宽限时间（秒）：已提供令牌的 TTL 会缩短至此值，以便停滞的传输可在此期间重试。
IMAGE_GENERATION_MCP_TRANSFER_LEASE_S	60.0	否	在途预留的崩溃处理程序回收时间窗口（秒）。
IMAGE_GENERATION_MCP_TRANSFER_MAX_UPLOAD_BYTES	104857600	否	单次上传的最大尺寸（字节）。
只有在 BASE_URL 已设置的 HTTP 或 SSE 传输上，才会注册 create_download_link / create_upload_link 工具和 /transfer/{token} 路由；链接令牌会存储在 IMAGE_GENERATION_MCP_KV_STORE_URL 中；上文的 IMAGE_GENERATION_MCP_TRANSFER_* 参数用于调整链接有效期和上传限制。安全性：IMAGE_GENERATION_MCP_ALLOW_LOCAL_FILE_INPUT 会通过参考图像路径授予调用方读取服务器文件系统的权限；仅应为可信调用方或本地单用户部署启用此项。

领域配置字段在 src/image_generation_mcp/config.py 中的 CONFIG-FIELDS-START / CONFIG-FIELDS-END 标记之间组合；环境变量读取通过 fastmcp_pvl_core.env(_ENV_PREFIX, "SUFFIX", default) 进行，以保持命名一致；字段约束写在 __post_init__ 中的 CONFIG-VALIDATE-START / CONFIG-VALIDATE-END 标记之间。每个字段的 metadata 中的 help 和 tags 会直接生成上方的表格，因此请确保其准确且完整。

关键设计决策

• 支持多提供商，通过能力发现而非功能标志。 每个提供商的 discover_capabilities() 会在启动时报告其实际支持的宽高比、质量、格式以及负面提示词支持情况；路由逻辑查询能力信息，而非硬编码枚举。新提供商只要实现该协议即可接入，无需修改路由器。（参见 docs/decisions/0001-…、0002-…、0007-…。）
• 每个模型的 style_profile 元数据通过 list_providers 展示。 固定列表的提供商（OpenAI、Gemini、占位符）使用精确键查找；SD WebUI 使用按正则顺序排列的模式表。配置文件包含生命周期标志（current / legacy / deprecated），并用于自动构建顶层 warnings 数组。（参见 docs/decisions/0009-…。）
• 混合式后台任务。 短调用（OpenAI 约 5 s）会在行内流式传输进度；长调用（SD WebUI 30-180 s）会作为后台任务运行，并通过 check_generation_status 轮询；客户端通过 task=True 选择模式。（参见 docs/decisions/0005-…。）
• 图像资源模型：内容寻址注册表 + 旁路 JSON 元数据 + 按需转换。 生成的图像会保留全分辨率原图；image://{id}/view?format=webp&width=512&crop_x=… 资源可按需进行格式转换、缩放和裁剪，无需重新生成。转换结果会缓存。（参见 docs/decisions/0006-…。）
• 风格库。 用户保存的 Markdown 简报（包含用于标签、宽高比和质量的 YAML frontmatter），由大模型按提供商进行解读，而非原样复制粘贴。风格库不同于每个模型的 style_profile：风格库是简报；style_profile 描述模型。（有关区别，请参见 docs/decisions/0008-… 和 0009-…。）
• 组合 fastmcp_pvl_core.ServerConfig，绝不继承。 领域配置写在 CONFIG-FIELDS-START / CONFIG-FIELDS-END 标记之间；环境变量读取通过 fastmcp_pvl_core.env(...) 进行，以保持前缀命名一致。