imagine-mcp

已于 2026-09-13 归档 — 此仓库已停止维护。请使用图像提供商的原生 API，而非此 MCP 服务。现有安装仍可运行，但不会收到更新或支持。

imagine-mcp

mcp-name: io.github.n24q02m/imagine-mcp

为 AI Agent 提供图像和视频理解与生成能力——支持 Gemini、OpenAI 和 Grok。

n24q02m 的姊妹项目（点击展开）

| 项目 | 标语 | 标签 | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | AI Agent 在共享文件夹中彼此聊天——无需人工转发，无需编排器，wor... | 工具 | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | 用于高效利用令牌进行代码审查的知识图谱——语义搜索和调用... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | 双向 Google Drive 同步，支持 .driveignore 过滤器——rclone 引擎，Windows 托盘 | 工具 | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | 为 AI Agent 提供 IMAP/SMTP 邮件功能——阅读、发送、整理文件夹并管理 att... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | 面向 Godot Engine 的复合 MCP 服务——提供 17 个复合工具，支持 AI 辅助游戏... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | 面向 AI Agent 的 Markdown 优先 Notion——页面、数据库、内容块和评论... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | 可直接替换使用的 python-semantic-release 分支，内置发布安全防护（orp... | 工具 | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | 为 AI Agent 提供 Telegram 功能——支持两种 bo...上的消息、聊天、媒体和联系人 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP 服务（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | 面向 n24q02m MCP 服务的 Claude Code 插件市场——安装网页搜索... | 市场 | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | 为 AI Agent 提供图像和视频理解与生成——支持 Gemini、Op... | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | 用于通过 batchexecute API 批量操作 Jules 任务的 Chrome 扩展——a... | 工具 | | [mcp-core](https://github.com/n24q02m/mcp-core) | 用于构建 MCP 服务的共享基础组件——Streamable HTTP 传输、OAut... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | 结合混合搜索和嵌入式同步的持久化 AI 记忆。开放、免费、无限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | 通过 ONNX Runtime 和 GGUF 实现轻量级 Qwen3 文本嵌入与重排序 | 库 | | [skret](https://github.com/n24q02m/skret) | 无需服务端的密钥管理。 | 命令行工具 | | [tacet](https://github.com/n24q02m/tacet) | 一种自蒸馏神经符号级联，可将 LLM 成本分摊到知识... | 工具 | | [web-core](https://github.com/n24q02m/web-core) | 用于搜索、抓取、HTTP 安全和 st...的共享 Web 基础设施包 | 库 | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | 面向 AI Agent 的开源 MCP 服务：网页搜索、内容提取和库... | MCP |

目录

• 功能
• 安装
• Smithery
• 配置
• 命令行工具
• 远程（HTTP 模式）
• 文档
• 工具
• 比较
• 安全
• 从源代码构建
• 部署到 Cloudflare
• 部署
• 信任模型
• 贡献
• 许可证

## 功能

• 多模态理解 —— 描述、分类图像和视频，或对其进行推理（Gemini 可在一次调用中处理混合图像和视频）
• 图像生成 —— 支持 Gemini Imagen、OpenAI gpt-image、Grok Imagine 的文生图和图生图（编辑／局部重绘）
• 视频生成 —— 支持文生视频和图生视频（Gemini Veo 3.1、Grok Imagine Video）
• 3 个提供商 × 2 个级别 —— gemini／openai／grok 使用相同接口，支持 poor（低成本／快速）或 rich（高质量）；通过参数切换
• 开放模型直通 —— 理解功能通过 litellm 路由；可传入任意 provider/model，或配置有序模型链（无硬编码目录）
• 降级模式 —— 服务无需任何凭据即可启动，并会在添加密钥后显示可用的提供商
• 响应缓存 —— 基于磁盘缓存 understand 响应，TTL 可配置
• 双传输模式 —— 使用提供商环境变量的纯 stdio（默认），或支持多用户的 HTTP 模式，带令牌粘贴中继表单

安装

使用 uvx 运行（无需安装），或拉取容器镜像：

# uvx -- recommended, runs the published PyPI package
uvx imagine-mcp

# Docker
docker run -it --rm ghcr.io/n24q02m/imagine-mcp:latest

将其添加到 MCP 客户端：让客户端指向 uvx imagine-mcp 命令，并至少提供一个提供商密钥（参见配置）：

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": { "GEMINI_API_KEY": "AIza..." }
    }
  }
}

有关各客户端的代码片段（Claude Code、Codex、Gemini CLI、Cursor、Windsurf）和基于浏览器的 HTTP 设置，请参阅设置文档。

使用 AI Agent 安装 —— 将以下内容粘贴给你的 AI 编码 Agent：

按照以下步骤安装 MCP 服务 imagine-mcp： https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/imagine-mcp/setup-with-agent.md

Smithery

imagine-mcp 提供了 smithery.yaml，可通过 Smithery 安装和运行。该入口通过 stdio 启动已发布的 PyPI 包（uvx --python 3.13 imagine-mcp），并使用空配置架构——部署时无需填写设置字段。提供商密钥在运行时通过服务自身的凭据流程提供（stdio 模式下使用环境变量，HTTP 模式下使用浏览器设置表单；参见配置）。

配置

支持两种传输模式（默认使用 stdio；可通过 --http、MCP_TRANSPORT=http 或 TRANSPORT_MODE=http 启用 http）：

• stdio（默认）—— 单用户模式，仅从环境变量读取凭据。若未设置三个提供商密钥中的任何一个，则退出。
• http —— HTTP 守护进程。默认在 127.0.0.1 上本地自托管；如果设置了 PUBLIC_URL + MCP_DCR_SERVER_SECRET，则使用支持多用户的远程模式（按 JWT subject 隔离凭据）。在 HTTP 模式下，通过 /authorize 的浏览器表单输入凭据。

提供商密钥

所有密钥均为可选项——服务以降级模式启动，并显示已有密钥的提供商。至少设置一个密钥。

环境变量	提供商	获取密钥
GEMINI_API_KEY	Gemini（图像 + 视频）	aistudio.google.com/apikey
OPENAI_API_KEY	OpenAI（图像）	platform.openai.com/api-keys
XAI_API_KEY	Grok / xAI（图像 + 视频）	console.x.ai

调用工具时若未显式指定 provider，则按 XAI_API_KEY -> OPENAI_API_KEY -> GEMINI_API_KEY 的顺序，使用第一个已设置的密钥。

模型链（可选）

模型选择会直接传递给 litellm（understand）或原生提供商 SDK（generate）——没有硬编码的模型目录。每条链都是由 litellm provider/model 条目组成的 CSV；顺序即回退顺序。

环境变量	用途
UNDERSTAND_MODELS	understand 的有序模型链（litellm 回退）。为空且未显式指定 model 时，understand 会报错退出（没有内置默认值）。
GENERATE_MODELS	generate 的有序模型链。第一个条目用于选择原生提供商和模型。为空时使用提供商自身的最小内置默认值。
GENERATE_PROVIDER_PRIORITY	用于重新排序生成自动回退顺序的提供商名称 CSV。默认为 grok,openai,gemini。

理解功能通过 litellm 路由（直接传递 provider/model），因此任何 litellm 提供商均可使用——提供该提供商的 <PROVIDER>_API_KEY 即可。生成功能仍使用原生提供商 SDK（Gemini、OpenAI、Grok）。示例：

{
  "mcpServers": {
    "imagine": {
      "command": "uvx",
      "args": ["imagine-mcp"],
      "env": {
        "UNDERSTAND_MODELS": "gemini/<model-id>,openai/<model-id>",
        "GEMINI_API_KEY": "AIza...",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

运行时选项

config(action="set", key=..., value=...) 可在运行时调整 log_level、default_provider、default_tier 和 cache_ttl_seconds。

CLI

该包安装的 imagine-mcp 控制台命令没有子命令——它会直接启动 MCP 服务。通过单个标志或对应的环境变量来选择传输方式：

imagine-mcp            # stdio transport (default); reads provider keys from env vars
imagine-mcp --http     # HTTP daemon; credentials via the browser setup form

调用方式	等效环境变量	结果
imagine-mcp	未设置 MCP_TRANSPORT	stdio，单用户，使用环境变量凭据
imagine-mcp --http	MCP_TRANSPORT=http（或 TRANSPORT_MODE=http）	HTTP 守护进程——本地 127.0.0.1 可自托管；设置 PUBLIC_URL 和 MCP_DCR_SERVER_SECRET 时则可作为多用户远程服务

在 stdio 模式下，如果未设置任何提供商密钥，服务将退出。远程 HTTP 绑定选项（MCP_HOST、MCP_PORT）仅在设置了 PUBLIC_URL 时生效；请参阅配置。

远程（HTTP 模式）

HTTP 部署可为支持远程 HTTP MCP 服务的客户端提供服务。该服务受 OAuth 保护——未通过身份验证的请求会返回 401，并附带 WWW-Authenticate: Bearer 质询；凭据通过浏览器设置表单配置。将支持 HTTP 的 MCP 客户端指向 https://<your-host>/mcp，并完成 OAuth 流程即可连接。 如需部署，请参阅部署到 Cloudflare。

文档

完整文档请访问 mcp.n24q02m.com/servers/imagine-mcp/setup/：

• 设置 —— Claude Code、Codex、Gemini CLI、Cursor、Windsurf、mcp.json 的安装方法
• 模式概览 —— stdio / local-relay / remote-relay / remote-oauth
• 多用户设置 —— 基于 JWT sub 的凭据模型

工具

4 个 MCP 工具（understand、generate、config、help），以及 config__open_relay（由 mcp-core 注入的框架工具）：

工具	操作	描述
understand	--	描述或推理一个或多个图片／视频 URL。media_urls: list[str]、prompt: str、provider、tier、max_tokens。
generate	--	根据文本提示词生成图片或视频。media_type: image|video、可选的 reference_image_url、可选的 job_id（轮询视频任务）、aspect_ratio、duration_seconds。
config	setup_status、setup_skip、setup_reset、setup_complete、warmup、status、set、cache_clear（接受已弃用的别名 relay_status／relay_skip／relay_reset／relay_complete）	凭证与运行时配置：检查凭证状态、设置运行时参数（日志级别、默认提供方、TTL）、清除响应缓存。
help	--	关于 understand、generate 或 config 主题的完整 Markdown 文档。
config__open_relay	--	框架注入的辅助工具（mcp-core）；打开浏览器凭证表单。

模型选择由调用方决定（litellm provider/model 直通，或 *_MODELS 环境变量链）——请参阅上文的模型链。

对比

imagine-mcp 在各项能力上与直接竞品的对比：

能力	imagine-mcp	EverArt MCP	fal.ai MCP	Replicate Flux MCP
图片／视频理解	支持（描述／分类／推理图片和视频 URL）	不支持	不支持	不支持
图片生成	支持（文生图 + 通过 reference_image_url 进行图生图）	支持（单一 generate_image）	支持（文生图／图生图、编辑、局部重绘）	支持（单一 generate_image）
视频生成	支持（文生视频 + 图生视频，通过异步 job_id 轮询）	不支持	支持（文生视频／图生视频）	不支持
多提供方后端	支持（Gemini／OpenAI／Grok，自动回退）	不支持（仅 EverArt）	不支持（仅 fal.ai）	不支持（仅 Replicate Flux）
质量／成本等级	支持（各提供方均可选 poor，低成本快速，或 rich，高质量）	不支持	不支持	不支持
可自托管／开源	支持（Apache-2.0，stdio + HTTP 自托管）	支持（MIT，已归档）	支持（MIT）	支持（MIT，已归档）

安全性

• SSRF + LFI 防护——所有 media_urls 和 reference_image_url 都会在分发边界进行验证；只有 http:// 和 https:// 协议会传递给提供方。file://、ftp://、gopher:// 和不带协议的 URL 都会被拒绝。
• 错误中不包含凭证——返回前会对提供方的错误进行清理。
• 降级启动——缺少凭证不会阻止服务启动；受影响的操作会给出可执行的错误提示，而不会在启动时崩溃。
• 凭证存储——通过浏览器凭证表单提交的凭证会由 mcp-core 加密存储（AES-GCM，密钥绑定到机器），位置为 ~/.imagine-mcp/config.json。

工作区用户名（HTTP 设置表单）

浏览器凭证表单包含一个可选的工作区用户名字段。输入相同的用户名始终会进入同一个按 sub 划分的存储区，因此重新授权或更换设备后仍可访问你的提供方密钥，而不必将其绑定到每次 /authorize 往返时生成的一次性主体。留空则继续使用此前按授权划分的行为。

信任边界：如果表单由共享的 MCP_RELAY_PASSWORD 保护，用户名只是分区键，并非机密——任何知道该密码的人都可以输入任意用户名并访问对应存储区。对于可信群组，这没有问题；不可信的多租户部署则需要为每位用户设置机密，或改用委托式 OAuth。

**一次性迁移：**现有用户在此更改后必须重新输入一次凭证。不会删除任何内容；旧随机主体下存储的凭证只是无法再通过原方式访问。

从源代码构建

git clone https://github.com/n24q02m/imagine-mcp.git
cd imagine-mcp
mise run setup      # or: uv sync --group dev
mise run dev        # run the server in stdio mode (add --http for the HTTP daemon)

部署到 Cloudflare

在 Cloudflare 上以无服务器方式运行自己的 imagine 实例（Worker + Container + KV）。存储 仅使用 KV——每位用户的凭据库位于 KV 中；由于容器文件系统是临时的，生成结果仅返回 base64（IMAGINE_OUTPUT_MODE=base64）。

前提条件： Cloudflare 账户需使用 Workers Paid 计划——Containers 需要此计划（Cloudflare 免费层不包含 Containers）——并安装 wrangler CLI。

1. git clone https://github.com/n24q02m/imagine-mcp && cd imagine-mcp
2. wrangler login
3. 创建 KV 命名空间（imagine 仅使用 KV——不需要 D1 或 Vectorize），然后将 返回的 ID 粘贴到 wrangler.jsonc 中（<imagine-kv-namespace-id> 占位符）：

   wrangler kv namespace create imagine-kv
   

4. 将容器镜像推送到 Cloudflare 托管的注册表（CF Containers 无法直接从 外部注册表拉取镜像），然后在 wrangler.jsonc 中设置 <YOUR_ACCOUNT_ID>：

   docker pull ghcr.io/n24q02m/imagine-mcp:beta
   docker tag ghcr.io/n24q02m/imagine-mcp:beta imagine-mcp:beta
   wrangler containers push imagine-mcp:beta   # prints registry.cloudflare.com/<ACCOUNT_ID>/imagine-mcp:beta
   

5. 将 wrangler.jsonc 中其余占位符指向你自己的域名：<YOUR_PUBLIC_URL> （vars.PUBLIC_URL，例如 https://imagine.example.com）和 <YOUR_WORKER_DOMAIN> （routes 自定义域名模式，例如 imagine.example.com）。
6. 设置密钥。CREDENTIAL_SECRET（稳定的 JWT 签名密钥 + 每位用户的保险库密钥）和 MCP_DCR_SERVER_SECRET（证明这是有意部署的多用户服务）为必需项； MCP_RELAY_PASSWORD 用于控制浏览器设置表单的登录。提供方密钥是可选的 服务端默认值——用户通常会改为通过设置表单粘贴自己的密钥：

   wrangler secret put CREDENTIAL_SECRET
   wrangler secret put MCP_DCR_SERVER_SECRET
   wrangler secret put MCP_RELAY_PASSWORD
   wrangler secret put GEMINI_API_KEY       # optional provider default
   wrangler secret put OPENAI_API_KEY       # optional provider default
   wrangler secret put XAI_API_KEY          # optional provider default
   

7. 执行 wrangler deploy，然后打开你的 Worker 域名，并在浏览器中继表单中完成设置。

http 容器镜像已配置为多用户模式（MCP_TRANSPORT=http 已内置于 镜像目标中）。存储通过 MCP_STORAGE_BACKEND=cf-kv 映射到 Cloudflare（加密的 凭据库），并设置 IMAGINE_OUTPUT_MODE=base64，强制以 base64 格式响应，因此不会 将媒体路径写入临时容器文件系统。

部署

Cloudflare 部署由 CD 管理：发布版本会触发 .github/workflows/cd.yml 中的 deploy-cf 作业。该作业会检出已发布的标签，构建带有已发布版本标签的 http-slim 容器镜像，将其推送到 Cloudflare 托管的注册表，部署 Worker + Container 堆栈，并通过 canary 检查作为发布门槛——canary 失败会导致作业失败，而不是部署 有问题的版本，因此线上镜像始终对应已发布的不可变镜像标签。对该部署手动运行 wrangler deploy 会破坏发布版本与标签之间的对应关系，因此不属于受支持的方式； 若要运行自己的实例，请参阅 部署到 Cloudflare。

当前此作业已禁用：仓库 Actions 变量 CF_HOSTED_ENABLED 设置为 false，因此发布版本不会自动部署，也不会运行托管端点。 自托管（见上文）是当前启用的 HTTP 方式。

信任模型

此插件实现 TC-Local（绑定到机器，单一信任主体）。完整分类请参阅 mcp-core 信任模型。

模式	存储	加密	谁能读取你的数据？
stdio（默认）	~/.imagine-mcp/config.json	AES-GCM，绑定到机器的密钥	仅你的 OS 用户（文件权限 0600）
HTTP 自托管	与 stdio 相同	相同	仅你（管理员 = 用户）

贡献

完整的开发工作流、提交约定和发布流程请参阅 CONTRIBUTING.md。欢迎提交问题和参与讨论。

许可证

Apache-2.0——详见 LICENSE。