<h1 align="center">media-gen-mcp</h1>

> Claude Code 的「图像全家桶」—— 造图、画想法、看懂图,一句话搞定,全免费。

<p align="center">
 <img src="https://img.shields.io/badge/version-0.19.0-blue">
 <img src="https://img.shields.io/badge/license-MIT-green">
 <img src="https://img.shields.io/badge/MCP-compatible-purple">
</p>

**给 Claude Code 装一次,以后所有图像活儿都是一句话。** 设计师出图、程序员画架构图、运营做分享卡、财务抠发票表格 —— 生图 / 视频 + 识别 + 画图 / 卡片 / 二维码全覆盖,**全免费**(免费服务方 + 本地引擎,装上即用)。

每周做几次图、装 N 个工具记 N 套参数很烦?这里只装一次,所有图像场景都丢给 Claude。

<div align="center">

**简体中文** | [English](README.en.md)

</div>

## 目录

- [你说一句话,得到什么](#你说一句话得到什么)
- [60 秒上手](#60-秒上手)
- [能力全家桶](#能力全家桶)
- [配置详解](#配置详解)
- [常见问题](#常见问题)
- [这是给谁的](#这是给谁的)
- [支持作者](#支持作者)
- [License](#license)

---

## 你说一句话,得到什么

| 你说 …… | 你得到 |
|---|---|
| "画只赛博朋克猫,霓虹辉光" | AI 写实图,落盘到 `output/` |
| "生成 5 秒海边日落视频" | AI 视频 MP4(后台生成,完成通知你) |
| "画个架构图:客户端 → API 网关 → 订单服务 + 支付服务" | 矢量架构图 |
| "把这组销售数据画成柱状图" | 高清数据图表 |
| "做个指向 github.com 的二维码" | 矢量二维码 |
| "把 E=mc² 渲染成高清公式" | 矢量公式 |
| "做张深色渐变分享卡,标题 七月新品 🚀" | 排版好的分享卡(中文 + emoji 自动) |
| "识别这张发票截图里的表格" | 可粘贴的 HTML/Markdown 表格 |
| "把这张柱状图读成数据点" | 结构化 JSON 数据 |
| "描述一下这张图里有什么" | 自然语言回答 |
| "把这份 20 页 PDF 报告的文字全抠出来" | 整篇文本 / Markdown / JSON(数字版秒出,扫描件自动逐页 OCR) |
| "把这份合同扫描件提文字,水印和红章忽略掉" | 干净文本(自动剔除水印 / 红章 / 页眉页脚区域) |
| "这份双栏论文按阅读顺序合并成一段" | 单栏连续文本(多栏阅读序自动还原,不再串行错位) |
| "我现在能识别表格吗?中文 OCR 配好了吗?" | 当前能力清单 + 路由建议(哪个能用 / 哪个没配 / 该用什么) |

> 不用学工具名,不用装系统依赖,**Claude 自动挑最合适的方式完成**。

---

## 60 秒上手

核心思路:**画图 / 卡片 / 二维码 / 公式是本地引擎,识图(OCR 文字识别)也默认进程内兜底——默认路径不调 AI、不连网,装上即用**(例外:卡片非默认字体 / 彩色 emoji、架构图 `icon:` 图标首次会从 CDN 取资源;离线自动降级 —— emoji 变纯文本、图标省略、字体可经 fontPath 本地化)。只有 AI 写实图 / 视频才需要免费 API Key —— 把"第一张图"和"第一次读图"都提前到注册之前。

### 30 秒｜一行接入(零 Key)

```bash
# 一行装上(不带 Key,30 秒)
claude mcp add media-gen-mcp npx media-gen-mcp-server

# 重启 Claude Code → 输入 /mcp → 看到 media-gen-mcp ✓ Connected 即成功
```

### 30 秒｜免 Key 立刻出第一张图

直接对 Claude 说一句:

```
做张深色科技风的分享卡,标题:Claude Code 图像全家桶
```

→ 矢量图自动落盘到 `output/`,打开就能用。**你还没注册任何 API Key,已经拿到结果。**

下面这些也都是零 Key 零联网即时出:

- 「做个指向 github.com 的二维码」
- 「把 E=mc² 渲染成高清公式」
- 「画个架构图:客户端 → 网关 → 订单服务 + 支付服务 → 数据库,深色科技风」
- 「识别这张验证码图片里的数字」(OCR,默认进程内,不装任何东西)
- 「把这张截图里的英文文字提取出来」

### 想要中文 SOTA 识图 / 看图问答?配一行智谱 GLM Key(零部署,可选)

默认轻量引擎对英文 / 数字够用,中文准确率一般。**不想自建 PaddleX / vLLM,又想要中文 SOTA + 复杂表格 + 看图问答?** 配一行智谱 GLM Key 即可 —— 云端 **GLM-4.6V-Flash 永久免费**,零部署、零本地资源:

```bash
# ① 到 https://open.bigmodel.cn/console/apikey 注册免费账号 + 申请 api_key(格式 {id}.{secret})
# 注意:只接受 open.bigmodel.cn 标准 key;Code Plan key(ZAI_API_KEY)不可用 —— 它绑定 Z.ai 端点 + 白名单工具,违规调用会封号

# ② 写到 ~/.media-gen-mcp/config.json
{
 "providers": {
 "glm-vision": { "apiKey": "你的{id}.{secret}" }
 }
}

# ③ 回 Claude Code 说:"识别这张中文发票截图里的表格" / "这张图里有几个人?在做什么?"
# → 中文 SOTA 识别 + 看图问答,落盘 / 直接回答
```

> 配好后 MCP 自动纳入 fallback 链:**paddle → glm-vision → vlm → tesseract**;哪一档临时挂掉自动降级,你无感。详见[配置详解 · 档位 2](#档位-2智谱-glm-46v-flash云端免费零部署中文-sota--vqa)。

### 想要 AI 写实图 / 视频?再加免费 API Key(可选)

```bash
# ① 拿免费 API Key(推荐 Agnes,默认服务方)
# https://platform.agnes-ai.com/ → 注册 → API Keys → 复制 sk-xxx
# (智谱 cogview-3-flash / cogvideox-flash 也永久免费,可二选一或都配)

# ② 写到 ~/.media-gen-mcp/config.json(只配一家也行)
{
 "providers": {
 "agnes": { "apiKey": "sk-你的agnes-key" }
 }
}

# ③ 回 Claude Code 说:"画只赛博朋克橙猫,写实风"
# → AI 写实图落盘。视频同理:"生成 5 秒海边日落视频"
```

> 不想用 npx?全局装也行:先 `npm i -g media-gen-mcp-server`,再 `claude mcp add media-gen-mcp -s user "$(which media-gen-mcp-server)"`。

---

## 能力全家桶

> 直接对 Claude 说你想干嘛,它自动挑最合适的方式完成。下面按「你想做的事」分组 —— 你不用知道背后叫什么。

### 造一张图(从无到有)

**画一张写实照片或插画**
> 你:"画只赛博朋克橙猫,霓虹辉光,写实风"
> 得到:写实图落盘到 `output/`(也支持插画 / 产品概念图 / Logo 草稿 / 科幻场景)

**把一句话或一张图变成短视频**
> 你:"生成 5 秒海边日落视频"
> 得到:MP4 视频(3–18 秒;长视频后台生成,完成后通知你取片)

**抓一个图标或品牌 Logo**
> 你:"抓一个 GitHub 的 Logo,128 像素"
> 得到:20 万+ 图标库里的矢量 Logo,即下即用(GitHub / Twitter / Material / Lucide / Font Awesome 等)

**逆向 AI 生成图的提示词与参数**
> 你:"这张图是用什么 prompt、什么参数生成的?能复现吗?"
> 得到:结构化参数 —— 正向 / 负向 prompt、模型、采样步数、CFG、种子、尺寸(从 PNG 嵌入的 ComfyUI / A1111 元数据本地解析;Agnes 生成的图自带完整生成参数,拿到 prompt 可用 generate_image 一键复现)

### Google Flow 渠道(Veo 3.1 / Nano Banana,免 API Key)

**是什么**:接入你已登录 Google Flow 的本机 Chrome,把 Flow 的生成能力变成工具 —— 免 API Key,生图 **0 积分**,视频按积分计费(7-100/条,提交前必经**计费确认门**:第一次调用只返回积分预估+确认令牌,你确认后才真提交)。

**前置**(只需一次;跨机器通用,lasso 非必需):一台开了调试端口的 Chrome 并登录 labs.google/fx —— `lasso launch-chrome --port 9223 --idle-ms 0`(推荐,静默),或裸 Chrome `--remote-debugging-port=9223 --user-data-dir=~/.media-gen-mcp/chrome-profile` 后在窗口登录;MCP 自动经 CDP 直连,不依赖 lasso 进程。

**一句话能干什么**:

| 你说 …… | 得到 |
|---|---|
| "用 Flow 画一张 ……"(或配置链让生图自动走 Flow)| 0 积分 AI 图(Nano Banana 2/Pro/Lite,含 2K 放大)|
| "用 Flow 把这张图动起来 / 生成 8 秒视频" | Veo 3.1 / Omni Flash 视频(文生/图生/参考图一致性/首尾帧/延长/编辑/1080p 超分,超分 0 积分)|
| "Flow 还剩多少积分?/ 把这条视频下载下来 / 删掉这批废图 / 生成分享链接" | `flow_status` 全套资产管理,全程 0 积分 |

> 视频积分明细与各会员档价目随 `flow_status` 实时可查;渠道优先级配置(让"生图"自动走 Flow)见[配置详解](#配置详解)。

### 看懂一张图 / 一份 PDF(把图和文档变数据)

**从截图里抠出文字**
> 你:"把这张验证码里的数字读出来"
> 得到:纯文本(验证码 / 发票号 / 扫描文档 / 聊天记录都能抠)

**把表格图变成 HTML / Markdown**
> 你:"识别这张发票截图里的表格"
> 得到:可直接粘贴的 Markdown 表格(发票 / 报表 / 扫描件不用再手动重打)

**从图表反推原始数据点**
> 你:"把这张柱状图读成数据"
> 得到:JSON 结构化数据(柱状 / 折线 / 饼图都行;glm-vision/vlm 走 prompt 抽取,paddle 的 chart 字段是占位、真实数据在 markdown 描述里)

**让它用大白话讲讲这张图**
> 你:"这张图里一共有几个人?在做什么?"
> 得到:自然语言回答(看图问答 / 手写 / 公式 / 复杂场景理解)

**把整份 PDF 的文字抠出来**
> 你:"把这份 20 页 PDF 报告的文字全抠出来,导出 Markdown"
> 得到:整篇文本 / Markdown / JSON —— 数字版 PDF 直接抽文字层秒出,扫描件自动逐页渲染 + OCR;支持指定页码范围(`3` / `1-10` / `odd` / `last`)、忽略水印 / 页眉页脚区域、多页合并或分页输出;长文档后台跑,完成通知你取结果(发票 / 合同 / 财报 / 论文 / 扫描书都行)

**让识图 / 读 PDF 结果更干净、更顺读**
> 你:「把这份合同扫描件提文字,**水印和红章忽略掉**」「这份双栏论文**按阅读顺序合并**成一段」
> 得到:干净、连续的文本 —— 两个开关在识图 / PDF 提取里可用(**tesseract 完整支持;glm-vision/vlm 不返回 blocks,两开关会被跳过并提示;paddle 的块无坐标,忽略区域仅告警级**):
> - **忽略区域**:圈出水印 / 红章 / 页眉页脚 / 表头区域,识别结果自动剔除,合同 / 证书 / 扫描件不再被水印糊住
> - **多栏阅读序**:论文 / 报刊 / 简历 / 双栏 / 三栏排版,自动按人类阅读顺序合并成单栏连续文本,不再串行错位

**先问一句"我装的识别服务都能干啥"**
> 你:"我现在能识别表格吗?中文 OCR 配好了吗?手写识别能用吗?"
> 得到:当前能力清单 —— 四档识别服务哪个已配置 / 哪个没配 / 哪个正在冷却或出错,以及"要做表格识别该走哪个、手写识别该走哪个"的路由建议;**先问一句再动手,避免直接调用才发现报错**

### 把想法画清楚(免 Key,装上就能用)

**画结构图**
> 你:"画个架构图:客户端 → API 网关 → 订单服务 + 支付服务 → 数据库"
> 得到:矢量架构图(也支持流程图 / 时序图 / 类图 / ER 图 / 思维导图)

**画交互式 / 动态 HTML 图**(浏览器打开可交互,边数据流 + 节点动画,主题跟随系统深/浅色)
> 你:"画个架构图,浏览器打开能交互、能动、主题跟着系统走"
> 得到:单文件 HTML(D2 双调色板默认开箱即反色 + viewer 平移/缩放/主题切换/导出 SVG + 边数据流/依次高亮/节点入场三种动画,Motion Governor 自动守无障碍)

**画可下钻的嵌套架构图**(浏览器打开点层进入子架构,面包屑回溯任意层)
> 你:"把这套系统画成嵌套架构图:顶层 5 大模块,点'订单服务'进它的内部架构,再点进创建订单的时序图"
> 得到:单文件 HTML(点某层 → 切到那层内部架构,层级可任意嵌套,每层可以是架构图 / 时序图 / 类图 / ER 图 / 流程图;面包屑或 Esc 回任意祖先层;URL 深链分享到某一层;主题跟随系统深/浅色)

**把数据画成图表**
> 你:"把这组销售数据画成柱状图"
> 得到:高清数据图表(柱状 / 折线 / 饼图 / 面积 / 散点,丢一串数字或一份 CSV 都行)

### 做卡片 / 海报 / 二维码(发出去好看)

**做分享卡 / OG 图 / 引言卡 / 封面 / 海报**
> 你:"做张深色渐变分享卡,标题 七月新品 🚀"
> 得到:排版精美的卡片(标题、副标题、渐变色、辉光、彩色 emoji、Logo 内嵌全自动,中文与日文汉字不乱码)

**生成二维码**
> 你:"做个指向 github.com 的二维码"
> 得到:矢量二维码(URL / 文本都行,海报印刷也清晰)

**把数学公式渲染成高清图**
> 你:"把 E=mc² 渲染成高清公式"
> 得到:矢量公式(LaTeX、复杂分式、化学方程式都支持)

### 做酷炫动效 / 科技感图形(同输入永远同输出)

**把 SVG 渲染成高清 PNG**
> 你:"画一个带辉光、星场、景深的科技感背景"
> 得到:酷炫 PNG,自动选最佳渲染方式保真不失真

**把 HTML / CSS 动画变成视频**
> 你:"做一个 3 秒的产品片头动画,渐变色 + 粒子"
> 得到:MP4 / GIF / WebM 视频(产品片头 / 品牌动画 / 动效演示,逐帧渲染,同输入永远同输出)

> **渲染浏览器依赖**:动效视频与滤镜 SVG 的 100% 保真渲染推荐 **lasso 渲染档**(确定性旗标内置、空闲 10 分钟自动回收、与本工具的日常 Chrome 完全隔离)——`npm i -g lasso-mcp` 后跑一次 `npx -y lasso-mcp render-chrome --ensure` 即装;`MEDIA_GEN_RENDER_MODE=attach` 钉死该档(CI/验收)。未装 lasso 时滤镜 SVG 自动降级 resvg(~92% 保真),动效视频返回带修复指引的结构化错误(legacy 自管池已退役,2026-09-03)。

> **小提示**:造图 / 读图走联网 AI;画图 / 卡片 / 二维码 / 动画是本地引擎 —— **装上就能用、矢量高清、同样的输入永远出同样的图**。

---

## 配置详解

> 一句话:**结构化能力(画图 / 图表 / 卡片 / 二维码 / 公式)零配置开箱即用;AI 生成配一行 API Key;识图默认零配置,要中文 SOTA / 表格 / 图表才自托管。** 你想用的能力决定要配什么 —— 不用全配。

### 按「我想干什么」查配置

| 你想干什么 | 要配什么 | 配了立刻能用 |
|---|---|---|
| 画架构图 / 数据图表 / 卡片 / 二维码 / 公式 | **什么都不用配** | 本地引擎,装完即用 |
| 酷炫动效视频 / 滤镜 SVG 100% 保真(`render_video` / `render_svg` Chrome 后端) | 推荐装 **lasso 渲染档**:`npm i -g lasso-mcp` 后跑一次 `npx -y lasso-mcp render-chrome --ensure`(空闲 10 分钟自动回收) | 装上即用;未装 lasso 时滤镜 SVG 自动降级 resvg(~92% 保真),动效视频返回带修复指引的结构化错误(legacy 自管池已退役) |
| AI 写实图 / AI 视频(文生图、文生视频) | 配一家免费 API Key(Agnes 或智谱,二选一) | 联网生成,落盘到 `output/` |
| 用 Google Flow 生图(0 积分)/ 管理生成资产 | **不用配 Key**:本机 Chrome 登录 Flow 即可(`lasso launch-chrome` 启动) | 生图 / 放大 / 上传 / 删除 / 分享 / 取消 / 查询全 0 积分;视频按积分计费(7–100 积分/条) |
| OCR 文字识别(英文 / 验证码 / 数字 / 简单文档) | **什么都不用配** | 默认走进程内轻量引擎,装完即用 |
| 中文 OCR / 发票表格 / 图表读数 / 看图问答 / 手写 / 公式 | **配一行智谱 GLM Key**(零部署,云端永久免费)**或** 自托管 PaddleX / vLLM | 配 GLM Key 即开即用;自托管服务跑起来后填一行 baseUrl |
| **PDF 文字提取**(数字版 / 扫描件 / 多页) | 装两个依赖 `npm i pdfjs-dist @napi-rs/canvas`(首次用 PDF 时装) | 数字版 PDF 秒出;扫描件按上面 OCR 档位走(默认零配置也能跑) |
| **去水印 / 红章 / 页眉页脚、多栏阅读序还原** | **什么都不用配** | 调识图 / PDF 工具时直接说"Claude,忽略水印"或"按阅读顺序合并",自动应用 |
| **查当前识别能力**(哪个能用 / 哪个没配) | **什么都不用配** | 直接问,Claude 回一份当前能力清单 + 路由建议 |

---

### 一、生成类配置(AI 生图 / 视频)

**配一家免费 Key 就够**(推荐 Agnes,默认服务方;智谱备选,中文场景原生优化):

```json
{
  "providers": {
    "agnes": { "apiKey": "sk-你的agnes-key" },
    "zhipu": { "apiKey": "你的智谱-key" }
  }
}
```

- **Agnes**(推荐):https://platform.agnes-ai.com/ → 注册 → API Keys → `sk-xxx`
- **智谱**:[open.bigmodel.cn](https://open.bigmodel.cn/) → API Keys(免费模型 `cogview-3-flash` / `cogvideox-flash` 永久免费)
- 配两家更稳:任一家限流/波动,另一家自动顶上,零感知零重复扣费
- 配置文件:`~/.media-gen-mcp/config.json`(Windows:`%USERPROFILE%\.media-gen-mcp\config.json`);**没有也不崩** —— 结构化能力与默认 OCR 照常工作

**渠道优先级链(可选)**——一行让"生图"自动走 Flow 免费档:

```json
{
  "imageProviderPriority": ["flow", "agnes", "zhipu"],
  "videoProviderPriority": ["agnes", "zhipu"]
}
```

- **链即开关**:渠道列进链 = 启用(链头即默认),不列 = 不启用;链头失败自动按序回落(60 秒熔断,不反复重试);显式 `provider="flow"` 点名永远合法且失败直抛(环境不可用返回带启动指引的 `[flow] S1xx`,绝不静默换渠道)
- **视频默认不走 Flow**(消耗积分,刻意不进默认链):要么写进 `videoProviderPriority` 自担积分,要么每次显式 `provider="flow"`
- **计费确认门(两段式,默认开)**:Flow 视频第一次调用不提交,只返回 `{needConfirm, estimatedCost, confirmToken}`;**原参数 + confirmToken** 再调才真提交。令牌 10 分钟有效、与全部计费参数绑定(改任一项失效);当前会员档不可用的 key 不发令牌直接拒绝并附各档价目;0 积分操作与非 Flow 渠道不触发。关闭:`"flow": { "videoConfirm": false }`

**Flow 资产管理(全 0 积分)**:`flow_status` 支持查积分/查状态/下载,以及分享(`shareMediaIds`)/取消(`cancelMediaIds`)/批量删除(`deleteMediaIds`)。配套 `"flow": { "toolDeadlineMs": 110000 }` 为 Flow 长操作设工具级截止(防卡死,超时转 `[flow] S410`,底层不取消,稍后经 `flow_status` 复查)。

---

### 二、识别类配置(识图 / OCR / 表格 / 图表 / 视觉理解)

识别能力分 4 档,**按需选装,默认档位 1 零配置即用**:

| 档位 | 能干什么 | 要配什么 | 费用 |
|---|---|---|---|
| **1 默认**(进程内)| 英文/数字/验证码/简单文档 OCR | **零配置** | 免费 |
| **2 智谱 GLM-4.6V-Flash** | 中文 SOTA + 复杂表格 + 图表读数 + 看图问答(全 4 task)| **一行 Key**(推荐,零部署)| **永久免费** |
| **3 PaddleX** | 中文 SOTA + 发票表格 + 版面分析 | 自托管(GPU 12GB 或 CPU 8GB 起)| 免费开源 |
| **4 vLLM Qwen2.5-VL** | 看图问答/手写/公式/复杂场景 | 自托管(GPU 16-24GB)| 免费开源 |

> 大多数用户:**档位 1 + 配一行档位 2 的 GLM Key 就齐了**;档位 3/4 给有 GPU、想全离线的用户(部署细节/CUDA 要求/Unlimited-OCR 长文档进阶见 [doc/自托管部署指南](doc/自托管部署指南.md))。

**档位 2 配置(最常用)**:

```json
{
  "providers": {
    "glm-vision": { "apiKey": "你的{id}.{secret}" }
  }
}
```

- Key 申请:[open.bigmodel.cn](https://open.bigmodel.cn/console/apikey)(免费注册,格式 `{id}.{secret}`)
- ⚠️ 只接受标准 api_key;**Code Plan key(ZAI_API_KEY)不可用**(绑定 Z.ai 端点+白名单工具,违规调用会封号);多 key 轮换技术上支持但智谱协议禁止多账号,请自担合规风险
- 默认模型 `glm-4.6v-flash`(可经 `providers["glm-vision"].model` 换 `glm-4v-flash` 或付费视觉模型)

**档位 3/4 自托管**(服务跑起来后各填一行 baseUrl,细节见部署指南):

```json
{
  "providers": {
    "paddle": { "baseUrl": "http://127.0.0.1:8080" },
    "vlm":    { "baseUrl": "http://127.0.0.1:8000" }
  }
}
```

---

### 三、自动兜底机制(配了就不用管)

- **生成侧**:Agnes ↔ 智谱,任一家失败自动切另一家(60 秒内连续失败触发软切换,你不用重启、不用改配置)
- **识别侧**:默认轻量引擎(进程内兜底)→ 按能力自动降级(fallback 按 tier 序:paddle(10)→ glm-vision(9)→ vlm(8);tesseract 是默认头兼最后兜底)
- **唯一例外**:视频轮询取片时**不切换**(避免拿到错的结果)
- 你要做的:配两家生成 API Key + 可选装一档识别服务,剩下的交给 Claude

> 你机器跑不动 PaddleX 或 vLLM?**继续用默认轻量引擎即可**,MCP 不会因为没装本地服务而报错 —— 只是中文 SOTA / 表格 / 看图问答 这几项能力不可用,其它全照常。

---

## 常见问题

**Q:不装任何东西能用吗?**
A:能。装上 MCP 就有画图 / 卡片 / 二维码 / 公式 / 数据图表 + 英文 / 验证码 OCR,全部本地跑,零联网。

**Q:识别中文乱码吗?**
A:默认轻量引擎对英文 / 数字 / 简单文档够用,中文准确率一般。要中文 SOTA 自托管 PaddleX(GPU 12GB 或 CPU 4 核 8GB),详见上方[配置详解](#配置详解)。

**Q:AI 视频要等多久?**
A:5 秒视频约 1–3 分钟,18 秒视频可能 5–10 分钟。后台异步生成,完成后自动通知你取片;预估 ≤60 秒的会同步等。

**Q:我的 RTX 3060 能跑表格识别吗?**
A:能。PaddleX GPU 模式最低 12GB VRAM(RTX 3060 12GB 正好),CPU 模式 4 核 + 8GB 内存也能跑(慢 3–5 倍)。详见[配置详解](#配置详解)。

**Q:中文 / emoji / 渐变能正常出吗?**
A:能。分享卡通过内置中文字体 + 排版引擎全自动支持中文、日文汉字、彩色 emoji、渐变标题、辉光效果,无需额外字体配置。

**Q:支持 Mermaid 吗?**
A:不支持(需要浏览器)。用 D2 或 Graphviz 代替,能力等价且更稳,矢量输出。

**Q:踩限流(429)?**
A:免费层有每分钟请求数限制。配两家服务方(Agnes + 智谱)后自动切换,基本无感。

**Q:视频帧数限制?**
A:随分辨率递减 —— 1080p ≤ 241 帧(约 10 秒),720p 可达 441 帧(约 18 秒)。可问 Claude 查实时约束。

**Q:npx 连不上 / 启动慢?**
A:全局装也行:先 `npm i -g media-gen-mcp-server`,再 `claude mcp add media-gen-mcp -s user "$(which media-gen-mcp-server)"`。

**Q:能用敏感词 / 武器 / 战争题材吗?**
A:真实武器词会触发内容过滤。改用科幻设定词(如"未来战甲"、"机甲")可绕过,效果等同。

**Q:Claude 会不会选错工具?(比如「做张分享卡」时去调生图)**
A:这类模糊请求的路由已经做过校准 —— 「做卡片 / 海报 / OG 图」「把图表里的数据读出来」「做产品片头动画」「画架构图 / 流程图」「把这组数据画成柱状图」等会自动落到合适的专用工具,无需手动纠正。当然你也可以在请求里直接点名某个工具。

---

## 这是给谁的

- **Claude Code 重度用户** —— 每周都要做几次图像任务,不想为每件事装一个 MCP、记一套参数。
- **写技术文档 / 博客的开发者** —— 反复需要架构图、时序图、ER 图、数据图、公式,不想离开工作流。
- **个人开发者 / 独立产品** —— 关注成本(全免费)与可控(同输入同输出),不想为图像任务单独搭后端。
- **数据 / 财务 / 法务** —— 双向场景:把数据画成图表,从截图 / 发票 / **PDF 报告 / 合同**里反向抽数据点(水印 / 红章可忽略,双栏论文按阅读序合并)。
- **教育 / 学术** —— 学生从课件截图 / 扫描讲义 / 论文 PDF 提文字、把双栏论文合并成连续文本、问图表里读出的数据;老师把纸质试卷扫描件变成可编辑文本。
- **运营 / 内容创作者 / 公众号作者** —— 分享卡 / OG 图 / 海报 / 二维码,中文 + 彩色 emoji + 渐变开箱即用。

> **不太适合**:不用 Claude Code 的用户;只要单一能力且已搭好流水线的工程化团队;需要付费商用模型 / 训练微调 / 实时视频 OCR 的场景(这些超出免费 MCP 范围)。

---

## 💝 支持作者

如果 media-gen-mcp 帮到你,欢迎请作者喝杯咖啡 ☕

<div align="center">

微信 | 支付宝
:-: | :-:
<img src="doc/support-wechat.jpg" height="200" alt="微信赞赏"> | <img src="doc/support-alipay.jpg" height="200" alt="支付宝赞赏">

</div>

或 ⭐ [Star 这个仓库](../../stargazers)、[提 Issue](../../issues) / [发 PR](../../pulls) —— 都是对作者的鼓励与支持。

---

## License

**MIT** —— 主体代码随便用。

识别侧依赖全栈 **Apache 2.0**(tesseract.js + PaddleOCR + Qwen2.5-VL),企业商用无 license 风险。

---

> 技术细节:服务方与引擎都可插拔,结构化工具同输入同输出可入 git,失败自动切换服务方。完整文档见 `doc/` 目录。

<p align="center">
 <sub>Built for everyone who'd rather <strong>say it</strong> than <strong>script it</strong>.</sub><br>
 <sub>装一次,以后所有图像活儿都是一句话。</sub>
</p>