Claude Multimodal MCP

为 Claude Code 添加多模态识别能力的 MCP 插件

中文 | English

为什么需要这个？

Claude Code 是一个强大的 AI 编程助手，但它有一个明显的短板：不支持图片、视频、音频的识别。

在实际开发中，我们经常遇到这些场景：

• 看一个教程视频，想让 AI 帮我提取关键操作步骤
• 截了一张报错截图，想让 AI 直接分析错误原因
• 有一段语音录音，想转成文字整理
• 拿到一个 PDF 文件，想提取里面的表格数据

这些场景都需要多模态识别能力，但 Claude Code 的主模型本身不支持。

这个项目的解决方案：作为 Claude Code 的 MCP 插件，接入外部多模态 API，让 Claude Code 获得多模态识别能力。

它能做什么？

视频分析

你：帮我看看这个教程视频的关键步骤
Claude：正在分析视频...
        → 自动分段处理
        → 提取每帧画面内容
        → 转录所有语音
        → 输出带时间戳的结构化内容

图片识别

你：[粘贴一张报错截图]
Claude：识别到以下错误信息...
        → 提取所有文字
        → 分析错误原因
        → 给出解决方案

音频转录

你：帮我转录这段会议录音
Claude：正在处理音频...
        → 降噪处理
        → 逐段转录
        → 区分不同说话人
        → 输出完整文字稿

文档解析

你：帮我提取这个PDF里的表格
Claude：正在解析文档...
        → 逐页识别
        → 提取表格数据
        → 保持原始格式输出

工作原理

┌─────────────────────────────────────────────────────────┐
│                      Claude Code                        │
│                                                         │
│   用户输入（文字/文件路径）                               │
│         ↓                                               │
│   Claude 主模型（文字处理）                               │
│         ↓                                               │
│   需要识别图片/视频/音频？                                │
│         ↓                                               │
│   调用 MCP 工具 ──────────────────────┐                 │
└──────────────────────────────────────┼─────────────────┘
                                       ↓
┌─────────────────────────────────────────────────────────┐
│               Claude Multimodal MCP                     │
│                                                         │
│   接收文件路径 + 用户问题                                 │
│         ↓                                               │
│   文件预处理（压缩/降噪/格式转换）                        │
│         ↓                                               │
│   编码为 base64                                         │
│         ↓                                               │
│   发送到多模态 API ──────────────────┐                  │
└──────────────────────────────────────┼─────────────────┘
                                       ↓
┌─────────────────────────────────────────────────────────┐
│                 多模态 API 服务                          │
│           （OpenAI / Claude / MiMo / 其他）              │
│                                                         │
│   接收 base64 编码的文件                                  │
│         ↓                                               │
│   模型识别（图片理解/视频分析/语音转录）                   │
│         ↓                                               │
│   返回识别结果                                           │
└─────────────────────────────────────────────────────────┘

简单来说：Claude Code 负责文字处理和任务调度，本插件负责多模态文件的识别，两者配合完成完整的工作流。

支持的文件格式

| 类型 | 格式 | |------|------| | 图片 | JPG, PNG, WebP, GIF, BMP, TIFF, SVG, HEIC | | 视频 | MP4, MOV, AVI, MKV, WebM, FLV, 3GP | | 音频 | MP3, WAV, M4A, FLAC, OGG, AAC, OPUS | | 文档 | PDF, DOCX, XLSX, PPTX, TXT, MD |

快速开始

一键部署

# 克隆项目
git clone https://github.com/yourusername/claude-multimodal-mcp.git
cd claude-multimodal-mcp

# 运行一键部署脚本
python setup.py

脚本会自动：

1. 检查 Python 和 FFmpeg 环境
2. 安装依赖包
3. 引导你填写 API 配置
4. 测试 API 连接
5. 生成 Claude Code 配置

手动部署

# 1. 安装依赖
pip install -r requirements.txt

# 2. 创建配置文件
cp config.template.json config.json

# 3. 编辑 config.json，填入你的 API 信息

config.json 示例：

{
  "api_key": "你的API密钥",
  "api_endpoint": "https://api.example.com/v1/chat/completions",
  "multimodal_model": "你的模型名称"
}

配置 Claude Code

运行 python setup.py 后，脚本会自动生成 .mcp.json 文件。

将生成的内容添加到 Claude Code 的 MCP 配置中，然后重启 Claude Code 即可使用。

配置说明

必填配置

| 配置项 | 说明 | 示例 | |--------|------|------| | api_key | 多模态 API 密钥 | sk-xxx... | | api_endpoint | API 地址（OpenAI 兼容格式） | https://api.example.com/v1/chat/completions | | multimodal_model | 模型名称 | gpt-4-vision-preview |

可选配置

| 配置项 | 说明 | 默认值 | |--------|------|--------| | api_key_backup | 备用 API 密钥 | 空 | | api_endpoint_backup | 备用 API 地址 | 空 | | video_output_dir | 视频分析输出目录 | ./output | | video_max_segment_size_mb | 视频分段最大大小 | 70 | | base64_size_limit_mb | base64 编码大小限制 | 80 | | segment_concurrency | 并发处理数 | 3 |

API 兼容性

支持所有 OpenAI 兼容格式的多模态 API：

| API 服务 | 支持模型 | 兼容性 | |----------|----------|--------| | OpenAI | GPT-4 Vision, GPT-4o | ✅ | | Anthropic | Claude 3 Sonnet/Opus | ✅ | | 通义千问 | Qwen-VL | ✅ | | 智谱 | GLM-4V | ✅ | | 其他 | 任何 OpenAI 兼容格式 | ✅ |

使用示例

分析视频

你：帮我分析这个视频的主要内容
Claude：我来帮你分析这个视频。
        [调用 video_info 获取视频信息]
        [调用 video_analyze 进行分析]
        
        视频分析完成：
        - 时长：15分32秒
        - 主要内容：Python爬虫教程
        - 关键步骤：
          1. [00:30] 安装 requests 库
          2. [02:15] 发送第一个请求
          3. [05:40] 解析 HTML 内容
          ...

识别图片

你：[粘贴截图] 这个报错怎么解决？
Claude：识别到以下错误信息：
        ```
        ModuleNotFoundError: No module named 'requests'
        ```
        这个错误是因为没有安装 requests 模块。
        解决方法：运行 `pip install requests`

转录音频

你：帮我转录这段会议录音
Claude：正在处理音频...
        [调用 process_multimodal]
        
        转录完成：
        
        [00:00-00:30] 张三：今天我们讨论一下项目进度...
        [00:30-01:15] 李四：好的，目前后端已经完成了...
        [01:15-02:00] 王五：前端这边还需要两天...
        ...

GPU 加速

如果你的电脑有独立显卡，系统会自动使用 GPU 加速视频处理：

| GPU 类型 | 编码器 | 速度提升 | |----------|--------|----------| | Intel Arc | AV1 QSV | 3-5x | | NVIDIA | H.264 NVENC | 3-5x | | AMD | H.264 AMF | 2-3x | | 无独显 | libx264 (CPU) | 1x |

常见问题

Q: FFmpeg 未安装

A: 视频/音频处理需要 FFmpeg，下载地址：

• Windows: https://github.com/BtbN/FFmpeg-Builds/releases
• macOS: brew install ffmpeg
• Linux: sudo apt install ffmpeg

Q: API 返回错误

A: 检查 config.json 中的 api_key 和 api_endpoint 是否正确。

Q: 视频处理很慢

A: 大视频会自动压缩和分段处理，耐心等待即可。如果有独显会自动使用 GPU 加速。

Q: 支持哪些多模态 API？

A: 支持所有 OpenAI 兼容格式的 API，包括 OpenAI、Anthropic、通义千问、智谱等。

项目结构

claude-multimodal-mcp/
├── mimo_multimodal.py      # MCP 服务器主程序
├── browser_control.py      # 浏览器控制工具
├── pc_control.py           # 电脑控制工具
├── setup.py                # 一键部署脚本
├── config.template.json    # 配置模板
├── requirements.txt        # Python 依赖
├── .gitignore              # Git 忽略规则
└── README.md               # 项目说明

许可证

MIT License

致谢

• FastMCP - MCP 服务器框架
• FFmpeg - 多媒体处理工具

如果这个项目帮到了你，点个 ⭐ 支持一下！