image-mcp-hub：一个服务，让所有 Agent 共用文生图能力

社区里现成的文生图 MCP 服务器大多是 stdio 传输方案——每个客户端都要单独配置一遍进程和密钥，如果客户端一多或者多设备环境下就成了配置地狱。

image-mcp-hub 换了个思路：它把任意兼容 OpenAI 的文生图接口（/v1/images/generations）封装成一个常驻的 MCP 服务，通过 streamable HTTP 暴露出来，所有 Agent 共用一份配置，改一处全局生效。

核心思路：做一个 MCP 中间层。上游接口无论返回 URL 还是 base64，都由它统一下载、解码、保存为本地文件，Agent 拿到的永远是一个可以直接访问的本地图片链接。

解决什么问题

多客户端共享：多个 MCP 客户端共用同一批模型，无需为每个客户端单独配置 stdio 进程与密钥；客户端仅支持 HTTP 传输的也能接入。
统一管理：Web 界面统一管理模型增删、API key 轮换与用量统计，修改后对所有 Agent 即时生效。
抹平上游差异：上游返回形态不一（部分返回 URL、部分返回 base64），中间层统一处理，Agent 无需关注差异。

核心特性

单端口多路径：/mcp（MCP 端点）、/admin（Web 管理端）、/images/（图片访问）复用同一 HTTP 服务。
模型即工具：每个已配置模型对应一个 MCP 工具，工具名使用自定义 alias，支持按需增删。
参数透传：prompt 必填，size / n / quality / style / background / output_format 可选，均原样转发至上游。
response_format 内部处理：上游返回 url 时由中间层下载，返回 b64_json 时由中间层解码，统一保存为本地文件；扩展名按图片实际字节判定，与 output_format 无关。
API key 轮询：每个模型的 key 列表 round-robin 轮询，游标在内存推进、定时与退出时惰性落盘。
配置热加载：token、密码、清理规则、模型列表修改后即时生效，无需中断连接。
Web 管理端：中英双语、深浅主题、仪表盘（请求统计 / 趋势图 / 最近调用）、模型增删改查、图片浏览与全局设置。
统计持久化：请求统计定期写入 data/stats.json，重启后数据不丢失。

架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


Agents (A / B / Claude Code / Cursor / ...)
  │
  │  POST /mcp   ·   Authorization: Bearer <mcp_token>
  ▼
image-mcp-hub   (:12300 · Go · MCP)
  │  端点：/mcp (MCP·Bearer) · /admin (Web·密码) · /images/ (公开)
  │
  ├── POST /v1/images/generations ─────►  OpenAI 兼容上游
  │      上游返回 url → 中间层下载  /  b64_json → 中间层解码
  │
  ├── 保存图片 + sidecar .meta.json ──►  ./data/images/
  └── 写请求统计 ────────────────────►  ./data/stats.json

图片按 20060102-150405_uuid.png 命名，sidecar 元数据记录模型名、prompt、参数、上游信息；清理支持按时间（max_age_days）和按数量（max_count）两条独立规则，均设为 0 时永久留存。

技术栈

项目	说明
语言	Go
协议	MCP streamable HTTP
上游	OpenAI 兼容文生图接口
前端	管理端 SPA（go:embed 打包进二进制）
存储	本地文件 + JSON 统计持久化
部署	单二进制 / Docker（GHCR，linux/amd64 + arm64）

部署与使用

go build 后直接运行，或使用 Docker 镜像（配置、图片、统计统一存于卷 /app/data）。首次启动自动生成默认 config.json。

在管理端「模型」页面添加模型（alias、model_id、base_url、api_keys），即可供 Agent 调用。客户端接入把端点指向 /mcp 并携带 Bearer token 即可，Claude Desktop 填 claude_desktop_config.json，Claude Code 用 claude mcp add --transport http。

默认密码 password 与默认 token sk-123456 仅供本地体验，部署前务必修改。/images/ 无鉴权且默认开启目录列举，公网部署务必在反向代理层添加访问控制并启用 HTTPS。

常见问题速览

修改端口 / 存储目录为何要重启？ 二者在进程启动时固定；token、密码、清理规则与模型列表走热加载，即时生效。
重命名工具名后历史统计还在吗？ 在。统计以模型创建时分配的 UUID 为键，与工具名、模型 id 解耦，升级旧版本时历史数据会自动迁移。
不同渠道同 model id 怎么统计？ 各自独立计数，仪表盘以 model_id · 工具名 分行展示。
上游无法识别的参数会如何处理？ 原样透传，由上游自行忽略；response_format 由中间层接管。
key 轮询遇到失效的 key 会怎样？ 错误原样上抛，不做失效标记，可在管理端手动替换。
统计与图片会随仓库推送吗？ 不会，data/ 与 config.json 均已在 .gitignore 中排除。