multimodal-mcp

为 Codex（DeepSeek 等纯文本模型）补上多模态能力的本地 MCP server，提供 10 个工具：

工具	功能	依赖
mm_describe_image	看图并返回文字描述	智谱 GLM-4V-Flash（免费）
mm_transcribe_audio	本地 Whisper 转写音频	faster-whisper（首次使用联网下载模型）
mm_analyze_video	抽帧分析视频 + 音轨转写	GLM-4V-Flash + faster-whisper
mm_generate_image	文生图并保存 PNG	智谱 CogView-3-Flash（免费）
mm_generate_video	提交视频生成任务，返回任务 ID	智谱 CogVideoX-Flash（免费）
mm_query_video_task	查询视频任务结果，成功后下载 MP4	智谱 CogVideoX-Flash（免费）
mm_create_comic_script	小说→漫剧剧本 JSON（角色卡+分镜）	智谱 GLM-4.7-Flash（免费）
mm_start_comic_video	后台逐镜生成：出图→动画→配音	CogView-3-Flash + CogVideoX-Flash + edge-tts
mm_query_comic_video	查询漫剧进度，完成后返回成片	同上
mm_synthesize_speech	文字合成 MP3 语音	edge-tts（免费）

适用环境

• 开发与验证环境：macOS（Apple Silicon，Python 3.14，Codex CLI 0.146）。
• 一键安装脚本支持：macOS / Linux（bash）。Windows 暂不支持脚本安装，可手动安装（见下文）。
• 一键安装不限于新电脑：任何已装好 Codex 的电脑都可以运行；现有电脑第一次运行 = 安装，之后重复运行 = 升级。

前置要求

1. Codex（桌面应用）或 Codex CLI：必须先安装，一键脚本才能自动注册 MCP server。安装方式见 Codex 官方文档：https://developers.openai.com/codex
2. git：brew install git（macOS）或系统包管理器安装。
3. Python 3.11+：macOS 推荐 brew install python@3.12。
4. 智谱 API key（可选，安装时可输入）：到 https://bigmodel.cn 注册，GLM-4V-Flash（看图）、CogView-3-Flash（文生图）、CogVideoX-Flash（文生视频）均为免费档。

一键安装 / 升级（推荐）

在终端执行一条命令：

bash <(curl -fsSL https://raw.githubusercontent.com/LinJianKun/multimodal-mcp/master/scripts/install.sh)

脚本全自动完成以下所有步骤，无需再手动执行任何安装或注册命令：

1. 克隆仓库到 ~/multimodal-mcp（已存在则自动 git pull 升级）；
2. 创建 .venv 虚拟环境并安装全部依赖（mcp、faster-whisper、edge-tts、ffmpeg 等）；
3. 生成 .env 配置并提示输入智谱 key（也可以用 ZHIPU_API_KEY=xxx 环境变量免交互）；
4. 自动注册 Codex MCP server：codex mcp add multimodal -- <安装目录>/.venv/bin/multimodal-mcp（已注册且路径一致则跳过，路径不同自动重新注册）；
5. 自动修复 ~/.codex/models.json 的 supports_search_tool（先备份再修改，解决 DeepSeek 配置下 MCP 工具不可见的问题）；
6. 输出完成提示与下一步操作。

重复运行 = 升级：自动拉取最新代码并重装依赖，不会覆盖已有 .env。

可选环境变量：

变量	作用	默认值
MMCP_DIR	安装目录	~/multimodal-mcp
ZHIPU_API_KEY	免交互提供智谱 key	无（否则交互输入）
MMCP_SKIP_CODEX=1	跳过 Codex 注册（调试/无 codex 时）	不跳过
MMCP_MODELS_JSON	指定 models.json 路径	~/.codex/models.json

安装完成后：

1. 完全退出并重启 Codex（macOS 用 Cmd+Q，不是关窗口）；
2. 新会话输入 /mcp，确认 multimodal 已连接；
3. 让 Codex 执行“分析 /Users/<你的用户名>/multimodal-mcp/evaluations/samples/red.png”验证看图功能。

手动安装（可选，适合开发/审查代码时）

不想用一键脚本时，可以手动执行等价步骤：

git clone https://github.com/LinJianKun/multimodal-mcp.git
cd multimodal-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp .env.example .env
# 编辑 .env，填入 ZHIPU_API_KEY
codex mcp add multimodal -- "$(pwd)/.venv/bin/multimodal-mcp"
# 手动修复 ~/.codex/models.json：把所有模型的 supports_search_tool 改为 false（先备份）

使用示例

• “分析 /path/to/screenshot.png，这是什么报错？”
• “转写 /path/to/meeting.m4a，总结要点”
• “分析 /path/to/demo.mp4 的前 6 帧，说明界面变化”
• “生成一张赛博朋克风格的城市夜景图”
• “生成一段 5 秒的猫咪玩球视频”
• “把 /path/to/novel.txt 改编成漫剧并生成视频”
• “把‘你好，欢迎使用’合成为语音”

漫剧制作（小说→成片）

三步完成一部 AI 漫剧：

1. mm_create_comic_script(novel_path)：上传 .txt/.md 小说，自动生成剧本 JSON（角色卡 + 分镜）。长篇小说按 5000 字分章、摘要递进，支持 UTF-8 与 GBK 编码。剧本会保存到 outputs/comic/<小说名>/script.json，可先人工审阅/修改再开拍；
2. mm_start_comic_video(script_path, size="1024x1024")：后台逐镜执行 出图（CogView-3-Flash）→ 图生视频（CogVideoX-Flash）→ 多角色配音（edge-tts），限流自动退避重试，每镜产物缓存、支持断点续跑（resume_job_id）；
3. mm_query_comic_video(job_id)：查询进度，全部完成后自动合成 1080x1920 竖屏成片（含字幕），返回 MP4 路径。

默认一集 30 镜 × 5 秒 ≈ 2.5 分钟；快模式（1024x1024）一集约 1-2 小时，原生竖屏模式（1080x1920）约 6 小时+。免费档高峰限流较多，Job 在后台自动排队重试，可随时查询进度。

视频生成（异步两步式）

视频生成需要几分钟，MCP 工具单次调用有超时限制，因此拆成两个工具：

1. mm_generate_video(prompt, duration=5, size="1920x1080", fps=30, with_audio=false)：提交任务，返回任务 ID；
2. mm_query_video_task(task_id)：反复查询直到 SUCCESS，成功后自动下载 MP4 到 outputs/videos/ 并返回路径。

期间任务状态为 PROCESSING（生成中），可让模型每隔一段时间再次调用查询工具。

测试

.venv/bin/pytest -v

限制

• DeepSeek 得到的是工具返回的文字，精确读图不如原生多模态模型。
• 智谱免费模型有速率限制；edge-tts 依赖微软在线服务，偶发不可用。
• Whisper 首次转写需联网下载模型（默认 small）。
• 一键安装脚本仅支持 macOS / Linux；Windows 请走手动安装流程。