MiMo Understand Image MCP

一个给 Claude Code 使用的图片理解 MCP 服务。它把 Claude Code 的图片理解请求转发给小米 MiMo 多模态模型，用来弥补纯文本模型无法直接读取图片的问题。

这个项目最初的使用场景是：Claude Code 主模型接入了 mimo-v2.5-pro，但该模型不是多模态模型，遇到截图、UI 图、报错图、设计稿时无法直接输入图片。通过这个 MCP，Claude Code 可以在需要看图时调用 understand_image 工具，由 MiMo 图片理解模型完成图像分析。

功能特性

提供 Claude Code 可识别的 MCP 工具：understand_image
兼容 MiniMax understand_image 风格的基础参数
支持普通 MiMo API Key 和 Token Plan 专属 Key
支持单图和多图理解
支持本地图片路径、file://、HTTP/HTTPS 图片 URL、data:image/...;base64,...
自动把本地图片转成 base64 data URL 后发送给 MiMo
提供交互式安装脚本，适合新手配置 Claude Code
提供本地诊断脚本，用于排查 API Key 和 Base URL 是否配置正确

适用场景

让 Claude Code 分析截图里的报错、UI 问题或页面状态
对比两张截图的变化
让 Claude Code 阅读架构图、流程图、设计稿
在使用非多模态主模型时，为 Claude Code 补充图片理解能力

安全说明

请务必注意：

不要把真实 API Key 写进代码、README、截图或 GitHub 仓库
不要把 .env、本地 Claude Code 配置或任何包含 key 的文件提交到仓库
Token Plan Key 通常只适合在兼容的 AI 编程工具中交互式使用
不要把本项目改造成批量图片分析脚本、公开后端服务或多人共享代理

本仓库的示例里只使用占位符，例如：

your_regular_mimo_api_key
your_token_plan_key

环境要求

Node.js 18.18 或更高版本
Claude Code
小米 MiMo API Key，普通 Key 或 Token Plan 专属 Key 均可

快速开始

先克隆项目并安装依赖：

git clone https://github.com/YOUR_GITHUB_USERNAME/mimo-understand-image-mcp.git
cd mimo-understand-image-mcp
npm install
npm run build

然后运行交互式安装：

npm run setup

安装脚本会让你选择 key 类型：

1. 普通 API Key
2. Token Plan 专属 Key，通常以 tp- 开头

如果你不确定，并且你的 key 是从 Token Plan 套餐页复制的，通常选择 2。脚本提示“直接回车确认”的地方，可以不输入内容，直接按回车。

安装完成后，重启 Claude Code，输入：

/mcp

确认能看到 MiMoUnderstandImage，并且状态为 connected。

普通 API Key 配置教程

如果你使用的是普通 MiMo API Key：

运行：

npm run setup

key 类型选择：

输入 1 或 2 后回车，直接回车默认选择 2:

输入 1 后回车。

粘贴普通 MiMo API Key。
模型名默认 mimo-v2.5，直接回车确认。
API host 默认：

https://api.xiaomimimo.com

直接回车确认即可。

Token Plan Key 配置教程

如果你使用的是 Token Plan 专属 Key：

打开 MiMo Token Plan 页面，找到：

专属 API key，通常以 tp- 开头
兼容 OpenAI 接口协议的专属 Base URL

Base URL 通常类似：

https://token-plan-sgp.xiaomimimo.com/v1

运行：

npm run setup

key 类型选择：

输入 1 或 2 后回车，直接回车默认选择 2:

Token Plan 用户可以直接回车，默认选择 2。

粘贴 tp-... 开头的 Token Plan 专属 API Key。
模型名默认 mimo-v2.5，直接回车确认。
当脚本询问 Base URL 时，粘贴 Token Plan 页面里的“兼容 OpenAI 接口协议”Base URL，例如：

https://token-plan-sgp.xiaomimimo.com/v1

本地诊断

如果 Claude Code 提示 API Key 无效，可以先用诊断脚本单独测试：

npm run doctor

诊断脚本同样会让你选择普通 API Key 或 Token Plan Key。

如果诊断失败，常见原因是：

API Key 复制错了
Token Plan Key 使用了普通 API host
Token Plan Base URL 没有带 /v1
粘贴时带入了空格、换行或引号
套餐不可用、过期或没有对应权限

只有当 npm run doctor 显示：

Mimo API key works.

再重新运行：

claude mcp remove MiMoUnderstandImage
npm run setup

然后重启 Claude Code。

手动添加到 Claude Code

推荐使用 npm run setup。如果你想手动添加，可以使用下面的命令。

普通 API Key：

claude mcp add -s user MiMoUnderstandImage \
  --env MIMO_API_KEY=your_regular_mimo_api_key \
  --env MIMO_API_HOST=https://api.xiaomimimo.com \
  --env MIMO_MODEL=mimo-v2.5 \
  -- node /absolute/path/to/mimo-understand-image-mcp/dist/index.js

Token Plan Key：

claude mcp add -s user MiMoUnderstandImage \
  --env MIMO_API_KEY=your_token_plan_key \
  --env MIMO_API_HOST=https://token-plan-sgp.xiaomimimo.com/v1 \
  --env MIMO_MODEL=mimo-v2.5 \
  -- node /absolute/path/to/mimo-understand-image-mcp/dist/index.js

工具参数

单图

{
  "prompt": "请描述这张截图，并指出可能的 UI 问题。",
  "image_url": "/absolute/path/to/screenshot.png"
}

多图

{
  "prompt": "请对比这两张截图，说明页面发生了哪些变化。",
  "image_urls": [
    "/absolute/path/to/before.png",
    "/absolute/path/to/after.png"
  ]
}

参数说明

prompt：必填，图片分析问题
image_url：单张图片来源
image_urls：多张图片来源
max_tokens：可选，默认 1024
system：可选，自定义系统提示词

支持的图片来源：

HTTP/HTTPS 图片 URL
本地文件路径
file:// URL
data:image/...;base64,... URL

支持的本地图片格式：

JPEG
PNG
GIF
WebP
BMP

开发

安装依赖：

npm install

运行测试：

npm test

类型检查：

npm run typecheck

构建：

npm run build

项目结构

src/
  config.ts        # 读取环境变量配置
  image-input.ts   # 本地图片和 URL 输入归一化
  mimo-client.ts   # 调用 MiMo OpenAI 兼容接口
  index.ts         # MCP server 入口
scripts/
  setup.js         # Claude Code 交互式安装
  doctor.js        # API Key 和 Base URL 诊断
test/
  *.test.ts        # 单元测试

许可证

MIT

MCP Servers