mimo-vision-mcp

MCP Server：用小米 MiMo v2.5 多模态模型，为纯文本主模型（如 deepseek-v4-flash）补齐图像识别能力。

主模型没有视觉能力时，通过本 Server 把截图、UI 图、报错图、设计稿、照片等转成文字描述， 主模型据此继续推理。二次开发自 Mriestac/mimo-image-recognition-mcp（选型记录见下文）。

功能

图片输入支持：本地路径、http(s):// URL、file://、data:image/...;base64,...； 格式仅限 jpg/jpeg/png/gif/webp/bmp，单张 ≤10MB（官方限制）。

Related MCP server: Mimo Vision MCP

架构

主模型（纯文本）─ 图片路径/URL → MCP 工具
    → server 读图转 base64 → POST https://api.xiaomimimo.com/v1/chat/completions (mimo-v2.5)
    → 纯文本描述 → 主模型继续推理

安装

cd <仓库路径>        # 例如 C:\path\to\mimo-vision-mcp
uv sync --dev        # 创建 .venv 并安装依赖（mcp[cli]<2、httpx、python-dotenv）
Copy-Item .env.example .env
# 编辑 .env 填入 MIMO_API_KEY

注册到 Claude Code（全局）

cd <仓库路径>        # 例如 C:\path\to\mimo-vision-mcp
$key = ((Get-Content .env | Where-Object { $_ -match '^MIMO_API_KEY=' }) -split '=', 2)[1]
claude mcp add mimo-vision -s user `
  -e "MIMO_API_KEY=$key" `
  -e "MIMO_BASE_URL=https://api.xiaomimimo.com/v1" `
  -e "MIMO_VISION_MODEL=mimo-v2.5" `
  -- "$PWD\.venv\Scripts\python.exe" "$PWD\server.py"

验证：

claude mcp list            # 应列出 mimo-vision
claude mcp get mimo-vision
claude mcp inspect mimo-vision   # 协议级连通性自检

主会话中需 重启 Claude Code 或 /mcp 重连 后工具才出现。

两种 Key 的差异

mimo-v2.5-pro 是纯文本推理模型，视觉理解必须用 mimo-v2.5。

使用

主会话中对模型说，例如：

描述这张图：C:\path\to\your\image.png 提取这张报错截图里的文字：C:\path\to\error.png

模型会自动调用对应工具。

验证

uv run --env-file .env pytest tests/test_image_utils.py tests/smoke_test.py   # 离线单测
uv run --env-file .env pytest tests/test_api.py                               # 真实 API 直连

踩坑记录

• MiMo API 硬性要求：content 数组必须同时包含 image_url 与 text 对象， 角色必须 user，否则返回 400 Param Incorrect - text is not set（见 api_client.build_vision_message）。

• mcp SDK 2.x 移除了 mcp.server.fastmcp：pyproject 锁定 mcp[cli]>=1.2,<2.0。

• mcp 1.29 lifespan 是构造函数参数（非 @mcp.lifespan_context）；工具/资源通过参数注解 Context 注入。

• resource 有函数参数会被注册为模板资源（_templates）而非普通资源，list_resources 看不到——配置资源改为无参数函数。

• 认证头用 Authorization: Bearer（base 项目 Mriestac 原用 api-key，已修正）；单图大小上限按官方改 10MB；补充 file:// 输入支持。

配置项（.env）

选型记录

候选仓库（均已 clone 审阅后删除 _ref/）：

• 选定 base：Mriestac/mimo-image-recognition-mcp —— 天然用 OpenAI chat/completions 格式 + api.xiaomimimo.com，依赖轻（httpx），async 实现，工具/资源写法为标准 FastMCP。

• 备选：kuohao233/mimo-vision-mcp —— 工具更全（describe/analyze/ocr）但走 Anthropic /v1/messages 格式，重写请求层成本高；其工具设计（默认 prompt、OCR 提示词）已借鉴到本项目。

修复自 base 的 3 处问题：认证头、10MB 上限、file:// 支持，并新增 read_image_info 工具与 4 个独立工具拆分。