multimodal-mcp

给任意 MCP 客户端配上一双"眼睛"，让纯文本主模型也能处理图片。

核心设计：MCP 只把图片转成文字，不做推理。推理由你当前会话选的主模型完成（glm-5.2 / deepseek / qwen / 任何模型）。

工具总览

识别工具

附件工具

后台任务工具

管理工具

describe_image 的 image 参数自动判断图片来源：

返回结构化文字描述（OCR + 图表数据 + UI 细节），主模型基于描述自己推理。

稳定性处理：所有图片来源先嗅探真实类型（非图片直接拒绝，不会把任意文件内容发给视觉 API）；超过 2048px 或 4MB 的图自动缩到长边 1568px 并重编码为 JPEG——视网膜全屏截图从几 MB 压到几百 KB，避免上游体积限制和超时。单源上限 64MB。每个阶段都写 stderr 日志（分辨率、体积、耗时），排查时看 MCP 服务器 stderr 输出即可。

缓存与生命周期：描述缓存 TTL 1 小时，图片会话 TTL 30 分钟。数据仅在进程内存中，重启即清空。PDF 每次最多处理 20 页，多图最多 8 张。

同步识别：普通 describe_* 和 ask_image 工具直接等待视觉模型完成并返回最终文字描述，不会因超过一定时长就提前返回 job_id。等待是一个 await，不轮询、不产生额外视觉请求。网络/状态瞬态错误最多自动重试两次。

后台识别（opt-in）：start_recognition 立即返回 job 快照，get_recognition 可按需查询进度（最多等待 50 秒），cancel_recognition 可取消已提交任务。任务结果保留 1 小时，进程重启后失效。

OpenCode 用户须知：OpenCode 默认约 60 秒 MCP 请求超时，须在配置中将 mcp.multimodal.timeout 设为 960000（毫秒），覆盖服务端 900 秒任务总超时。运行 install.py 可自动写入此值。

Reasonix 用户须知：Reasonix 默认 MCP 调用超时 300 秒，低于服务端 900 秒任务总超时。在 ~/.reasonix/config.toml（或项目 ./reasonix.toml）里设置 [tools] mcp_call_timeout_seconds = 960。运行 install.py 会自动写入项目 .mcp.json 并打印此提示。

"剪贴板"路径解决客户端拦截粘贴图片的问题：截图后不粘贴到聊天框，打字说"看下我的截图"，工具直接读剪贴板。跨平台跨客户端。

Related MCP server: Vision Bridge MCP

项目架构

multimodal-mcp/
├── server.py              # MCP 服务入口，注册全部 12 个工具，图片来源解析与裁剪
├── recognition.py         # RecognitionRequest 与 RecognitionRunner，编排识别流程
├── providers.py           # openai / anthropic 双 provider 适配（请求构造、响应提取）
├── state.py               # 内存缓存：描述缓存（TTL 1h）、图片会话（TTL 30min）、LRU 淘汰
├── jobs.py                # 异步任务管理器：去重、状态追踪、超时、取消、容量限制
├── attachments.py         # OpenCode 附件缓存解析（~/.cache/opencode/multimodal-attachments）
├── claude_attachments.py  # Claude Code 附件缓存解析（~/.claude/image-cache/<session-id>/）
├── pdf_support.py         # PDF 页选择、文本提取 / 扫描页渲染（PyMuPDF）
├── install.py             # 跨平台安装脚本：检测客户端、写入 MCP 配置与规则文件
└── tests/                 # 15 个测试文件，覆盖全部模块

系统依赖

仅"剪贴板"路径需要：

URL / data URI / 文件路径 / base64 四种路径无依赖。

安装与配置

需要 Python ≥ 3.10（仅 local 模式）；uvx 模式只需 uv。

凭据

四个环境变量，写进客户端 MCP 配置的凭据字段：

主推理模型不在这里配——它是你客户端会话里选的那个。

• PROVIDER=openai：服务端请求 BASE_URL + /chat/completions

• PROVIDER=anthropic：服务端请求 BASE_URL + /v1/messages

各客户端的凭据字段名不一样：opencode 叫 environment，Claude / Cursor / Codex 叫 env。install.py 会自动用对的字段名。

方式 A：一键脚本（推荐）

在仓库目录里运行，自动检测已装客户端并写入配置 + 规则文件，幂等可重复跑：

python install.py              # 交互式
python install.py --yes        # 跳过确认

# 带凭据,一条命令配齐
python install.py \
  --provider openai \
  --base-url https://dashscope.aliyuncs.com/compatible-mode/v1 \
  --api-key sk-xxxxx \
  --model qwen3.7-plus

python install.py \
  --provider anthropic \
  --base-url https://api.anthropic.com \
  --api-key sk-ant-xxxxx \
  --model claude-3-7-sonnet-latest

# 强制 uvx / local 模式
python install.py --mode uvx --repo git+https://github.com/believe3344/multimodal-mcp
python install.py --mode local

跑完重启客户端即可。--api-key 会进 shell 历史，介意就跑完手动填。

方式 B：手动配置

不用 install.py，按下面格式写进各客户端配置。两种运行模式：

• uvx（不用 clone）：command 跑 uvx --from git+URL multimodal-mcp

• local（clone + venv）：command 跑 venv 里的 python + server.py

opencode（~/.config/opencode/opencode.json）— command 是数组，凭据字段叫 environment。OpenCode 需设 timeout 覆盖默认约 60 秒限制：

{
  "mcp": {
    "multimodal": {
      "type": "local",
      "command": ["uvx", "--from", "git+https://github.com/believe3344/multimodal-mcp", "multimodal-mcp"],
      "timeout": 960000,
      "environment": {
        "PROVIDER": "openai",
        "BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "API_KEY": "sk-xxxxx",
        "MODEL_NAME": "qwen3.7-plus"
      }
    }
  }
}

Claude Code / Desktop / Cursor（~/.claude.json / ~/Library/Application Support/Claude/claude_desktop_config.json / ~/.cursor/mcp.json）— command 字符串 + args 数组，凭据字段叫 env：

{
  "mcpServers": {
    "multimodal": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/believe3344/multimodal-mcp", "multimodal-mcp"],
      "env": {
        "PROVIDER": "openai",
        "BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "API_KEY": "sk-xxxxx",
        "MODEL_NAME": "qwen3.7-plus"
      }
    }
  }
}

Codex CLI（~/.codex/config.toml）— TOML，env 是 inline table：

[mcp_servers.multimodal]
command = "uvx"
args = ["--from", "git+https://github.com/believe3344/multimodal-mcp", "multimodal-mcp"]
env = { PROVIDER = "openai", BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1", API_KEY = "sk-xxxxx", MODEL_NAME = "qwen3.7-plus" }

Reasonix（项目级，推荐）— 在项目根目录放 .mcp.json，用 Claude Code 的 mcpServers schema（Reasonix 原生兼容，install.py 会自动写入）：

{
  "mcpServers": {
    "multimodal": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/believe3344/multimodal-mcp", "multimodal-mcp"],
      "env": {
        "PROVIDER": "openai",
        "BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "API_KEY": "sk-xxxxx",
        "MODEL_NAME": "qwen3.7-plus"
      }
    }
  }
}

Reasonix 全局配置在 ~/.reasonix/config.toml。Reasonix 默认 MCP 调用超时 300 秒，低于服务端 900 秒任务上限，长任务请在 ~/.reasonix/config.toml（或项目 ./reasonix.toml）里调大：

[tools]
mcp_call_timeout_seconds = 960

Reasonix 粘贴图片会存到项目根 .reasonix/attachments/，消息里带路径标记，规则已覆盖（见下文"粘贴附件"）。

local 模式：把上面 uvx 的 command/args 换成 venv python + server.py 绝对路径，凭据字段不变（opencode 仍 environment，其他仍 env）。command 必须是 venv 里的 python，否则缺 mcp / httpx 依赖。准备 venv：

cd /path/to/multimodal-mcp
uv venv --python 3.11 && source .venv/bin/activate
uv pip install -r requirements.txt

Windsurf / Cline：MCP 配置走各自 UI（Settings > MCP），格式同上。

规则文件

install.py 会自动把"何时调 describe_image"的规则写进各客户端规则文件（opencode AGENTS.md / Claude CLAUDE.md / Cursor .mdc / Codex AGENTS.md / Windsurf .windsurfrules / Cline .clinerules / Reasonix 项目 CLAUDE.md）。手动配置时需自行添加，模板见 RULES.md。

测试

重启客户端后：

1. 调 multimodal_config_status，确认 PROVIDER 正确且凭据都 set

2. 调 describe_image，image 留空（读剪贴板）或传 URL

或用 MCP Inspector 独立测试（不依赖客户端，需先在 shell 设置 PROVIDER / BASE_URL / API_KEY / MODEL_NAME）：

npx @modelcontextprotocol/inspector .venv/bin/python server.py

使用示例

截图

[用户] Cmd+Shift+4 截图,然后说"看下我的截图"
[agent] describe_image(image=None) → 读剪贴板 → 文字描述 → 回答

图片 URL

[用户] 描述这张图:https://example.com/chart.png
[agent] describe_image(image="https://...") → 下载 → 描述 → 回答

本地文件

[用户] 看 /tmp/screenshot.png 里的表格
[agent] describe_image(image="/tmp/screenshot.png") → 读文件 → 描述 → 回答

多图同步识别

[用户] 识别这三张图片
[agent] describe_images(...) → 持续等待识别 → 返回最终文字描述 → 同一回合回答

粘贴附件（占位符）

部分客户端在把图片粘贴到对话框后，会把原始图片变成 [Image 1] 占位符且不保留系统剪贴板数据。解析顺序：

1. 若消息里出现 [Image: source: /绝对路径/文件.png] 格式的路径标记，直接提取绝对路径传给 describe_image 或 describe_images。

2. 否则，若消息里出现 [Multimodal attachment paths: ...] 标记，直接把标记中的路径传给 describe_image 或 describe_images。

3. 否则，若消息里出现 Reasonix 附件标记（@.reasonix/attachments/... 路径，或 [image attachment available at @.reasonix/attachments/<文件>; ...]），把其中的相对路径基于项目根目录解析为绝对路径，传给 describe_image 或 describe_images。

4. 否则，若无路径标记但有 N 个占位符，按客户端选择工具：

   • Claude Code：调用 describe_claude_pasted_images(count=N)。Claude Code 把粘贴图片存在 ~/.claude/image-cache/<session-id>/<N>.png，数字文件名就是占位符序号；工具通过 server 进程环境变量 CLAUDE_CODE_SESSION_ID 精确定位当前会话目录（env 缺失时退化为最新会话目录），无需任何配置。

   • OpenCode：调用 describe_pasted_images(count=N) 读取 ~/.cache/opencode/multimodal-attachments 中的最新 N 张附件；工具会恢复原始粘贴顺序。

5. 若附件目录为空或数量不足，回退为 describe_image(image="") 读取系统剪贴板。

OpenCode 侧的附件缓存由插件 ~/.config/opencode/plugins/multimodal-attachment-bridge.js 写入，OpenCode 会自动加载。临时图片仅当前用户可读，1 小时后在下次 OpenCode 启动时清理。

Reasonix：图片粘贴由 Reasonix 接管（macOS/Linux Ctrl+V，Windows Alt+V，或 /paste-image），附件保存到项目根目录 .reasonix/attachments/clipboard-<时间戳>-<序号>.png，消息里会注入 @.reasonix/attachments/<文件> 路径标记（图片字节不内联）。主模型不支持视觉时直接把这些路径传给 describe_image / describe_images 即可，不需要额外的缓存解析工具。

故障排查

| 现象 | 排查 | |---|---|---| | Missing API key | 凭据字段里 PROVIDER / API_KEY / BASE_URL / MODEL_NAME 没填齐，或字段写错（opencode 是 environment 不是 env） | | HTTP 401 | Key 错或没开通该模型 | | HTTP 404 | PROVIDER=openai 时 BASE_URL 不是 /v1 根，或 PROVIDER=anthropic 时 BASE_URL 误填成 /v1/messages 之类的完整路径 | | 大图超时 / 间歇失败 | 已在服务端自动压缩；仍失败就看 MCP 服务器 stderr 日志里的体积与耗时 | | OpenCode 约 60 秒超时 | 未配 timeout 字段。运行 install.py 自动写入 960000 ms，或手动在 opencode.json 的 mcp.multimodal 下加 "timeout": 960000 | | Claude Code 工具调用超时 | 未配 MCP_TOOL_TIMEOUT。运行 install.py 自动写入 ~/.claude/settings.json 的 env.MCP_TOOL_TIMEOUT=960000，或手动添加 | | Reasonix 长任务超时 | 未配 [tools] mcp_call_timeout_seconds（默认 300 秒，低于服务端 900 秒上限）。在 ~/.reasonix/config.toml 或项目 ./reasonix.toml 设为 960 | | not a supported image | 输入不是图片文件（只支持 PNG/JPEG/GIF/WebP/BMP） | | clipboard has no image | 截图后别再复制其他内容；macOS 用 Cmd+Ctrl+Shift+4 才直接进剪贴板 | | 描述模糊 | detail 设 high，或自定义 instruction | | agent 不自动调 | 检查客户端是否加载 MCP、规则文件是否被读取 |

限制

• 每次调用一次视觉模型往返，延迟取决于该模型。

• 视觉模型描述什么，主模型就只看什么。极小细节可能丢失——用 instruction 写具体。

• 走 stdio；远程多人共用可改 streamable_http。