mimo-vision-mcp

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

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

功能

工具	说明
describe_image(image, prompt?)	单图理解（默认给详细描述）
analyze_images(images, question)	多图联合分析（前后对比 / A/B 方案）
extract_text_from_image(image)	纯 OCR，保留换行缩进
read_image_info(image)	只做本地校验，不调 API（排查输入问题）
mimo://config 资源	查看脱敏配置

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

架构

主模型（纯文本）─ 图片路径/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 的差异

Key 类型	前缀	MIMO_BASE_URL
普通按量付费	sk-	https://api.xiaomimimo.com/v1
Token Plan	tp-	https://token-plan-cn.xiaomimimo.com/v1

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）

变量	默认	说明
MIMO_API_KEY	—	必填
MIMO_BASE_URL	https://api.xiaomimimo.com/v1	Token Plan 需改
MIMO_VISION_MODEL	mimo-v2.5	视觉模型名
MIMO_MAX_TOKENS	2048	最大输出 token
MIMO_TIMEOUT	60	请求超时（秒）
MIMO_ENABLE_THINKING	False	是否输出思考过程（更慢）
MIMO_MAX_IMAGE_BYTES	10485760	单图上限（10MB）

选型记录

候选仓库（均已 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 个独立工具拆分。