内容
# MiMo Vision MCP
[English](README_EN.md) | 中文
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
> 一个基于 Model Context Protocol (MCP) 的本地视觉服务，为 Codex、Claude Desktop、GitHub Copilot 等 AI 客户端提供强大的图片分析能力。
## ✨ 功能特性
### 核心能力
- **多图分析**：支持单图、多图（最多16张）和图片对比分析
- **多源输入**：支持本地图片路径、公网图片 URL、Base64 编码图片
- **智能模式**：通用识别、OCR、截图分析、流程图布局检查、结构化 JSON 提取
- **区域分析**：支持裁剪指定区域进行二次识别分析
- **深度控制**：可控制 MiMo 深度思考模式和最大输出 token 数
- **双接入模式**：支持 Token Plan 套餐和按量 Token API，默认保持 Token Plan
### 工具集
| 工具 | 描述 | 适用场景 |
| ------------------------ | ------------------------ | ---------------------- |
| `analyze_image` | 单图通用分析 | 快速图片识别 |
| `analyze_images` | 多图分析（支持多种模式） | 批量图片处理、对比分析 |
| `compare_images` | 多图差异与共同点比较 | 版本对比、差异检测 |
| `check_layout` | 流程图/示意图布局检查 | UI/UX 设计审查 |
| `extract_image_data` | 结构化 JSON 数据提取 | 数据处理、自动化流水线 |
| `find_images` | 在允许目录内查找图片 | 文件管理、批量处理 |
| `get_image_metadata` | 读取图片元数据 | 文件信息获取 |
| `inspect_image_region` | 裁剪区域二次识别 | 细节分析、局部放大 |
## 🚀 快速开始
### 环境要求
- Python 3.11 或更高版本
- MiMo API Key（[申请地址](https://mimo.xiaomi.com)）
### 安装
```bash
# 克隆项目
git clone https://github.com/Sunset-OrangeSea/mimo-vision-mcp.git
cd mimo-vision-mcp
# 创建虚拟环境
python -m venv .venv
# 激活虚拟环境
# Windows
.\.venv\Scripts\Activate.ps1
# Linux/macOS
source .venv/bin/activate
# 安装项目
pip install -e ".[dev]"
```
### 配置
创建 `.env.local` 文件（不要提交到 Git）：
```bash
# 必需配置
MIMO_API_KEY=your_api_key_here
# 可选配置（以下为默认值）
MIMO_API_MODE=token_plan
MIMO_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
MIMO_MODEL=mimo-v2.5
MIMO_ALLOWED_PATHS=C:\;D:\;E:\;F:\
MIMO_MAX_IMAGE_PIXELS=40000000
MIMO_MAX_PROMPT_CHARS=8000
MIMO_MAX_COMPLETION_TOKENS=4096
MIMO_THINKING=enabled
MIMO_MAX_SEARCH_RESULTS=100
```
`MIMO_API_MODE` 支持两种值：
- `token_plan`：Token Plan 套餐，使用 `tp-...` Key；默认地址为
`https://token-plan-cn.xiaomimimo.com/v1`。
- `token_api`：按量 Token API，使用 `sk-...` Key；默认地址为
`https://api.xiaomimimo.com/v1`。
选择 `token_api` 时可以省略 `MIMO_BASE_URL`，服务会自动使用对应默认地址；显式设置
`MIMO_BASE_URL` 时，以显式地址为准。两种 Key 独立，不能混用。
#### Token Plan 配置
```dotenv
MIMO_API_MODE=token_plan
MIMO_API_KEY=tp-your-token-plan-key
```
#### Token API 配置
```dotenv
MIMO_API_MODE=token_api
MIMO_API_KEY=sk-your-token-api-key
```
除非需要区域节点或自定义代理，否则不需要额外填写 `MIMO_BASE_URL`。修改模式后，
仅新启动的 MCP 进程会读取新配置；已运行的进程继续保持原配置，不会被本项目主动重启。
### 运行
```bash
# 启动 MCP 服务
python -m mimo_vision_mcp
# 或使用安装后的命令
mimo-vision-mcp
```
## 📦 客户端配置
### Codex
参考 `examples/codex-config.toml`，或在用户级配置 `C:\Users\<username>\.codex\config.toml` 中添加：
```toml
[mcp.mimo-vision]
command = "python"
args = ["-m", "mimo_vision_mcp"]
```
### Claude Desktop
参考 `examples/claude_desktop_config.json`，在 Claude Desktop 配置中添加：
```json
{
"mcpServers": {
"mimo-vision": {
"command": "python",
"args": ["-m", "mimo_vision_mcp"]
}
}
}
```
### GitHub Copilot
参考 `examples/copilot-mcp-config.json`，配置 MCP 服务器。
## 🧪 测试与验证
```bash
# 设置 Python 路径
export PYTHONPATH=$(pwd)/src # Linux/macOS
$env:PYTHONPATH = (Join-Path (Get-Location) "src") # Windows PowerShell
# 运行测试
python -m pytest -q
# 代码编译检查
python -m compileall -q src tests
# 代码风格检查
python -m ruff check .
# MCP 协议验证（不需要 API Key）
python scripts/probe_mcp.py
# 完整功能测试（需要 API Key）
python scripts/smoke_test_mimo_vision.py
```
## 📁 项目结构
```
mimo-vision-mcp/
├── docs/ # 文档目录
│ └── superpowers/
│ ├── plans/ # 开发计划
│ └── specs/ # 技术规格
├── examples/ # 配置示例
│ ├── claude_desktop_config.json
│ ├── codex-config.toml
│ └── copilot-mcp-config.json
├── scripts/ # 工具脚本
│ ├── probe_mcp.py # MCP 协议验证
│ └── smoke_test_mimo_vision.py # 功能测试
├── src/ # 源代码
│ └── mimo_vision_mcp/
│ ├── __init__.py
│ ├── __main__.py # 程序入口
│ ├── config.py # 配置管理
│ ├── image_input.py # 图片输入处理
│ ├── provider.py # MiMo API 调用
│ └── server.py # MCP 服务器实现
├── tests/ # 测试代码
│ ├── test_config.py
│ ├── test_image_input.py
│ ├── test_image_tools.py
│ ├── test_mcp_protocol.py
│ ├── test_provider.py
│ └── test_server.py
├── .gitignore
├── CHANGELOG.md # 更新日志
├── CONTRIBUTING.md # 贡献指南
├── LICENSE # MIT 许可证
├── pyproject.toml # 项目配置
├── README.md # 中文文档
└── README_EN.md # 英文文档
```
## 🔧 开发指南
### 开发环境设置
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 代码格式化
black src tests
# 代码检查
ruff check src tests
```
### 添加新工具
1. 在 `src/mimo_vision_mcp/server.py` 中定义工具函数
2. 使用 `@mcp.tool()` 装饰器注册工具
3. 添加相应的测试用例
4. 更新 README 文档
### 测试覆盖率
```bash
# 运行测试并生成覆盖率报告
python -m pytest --cov=mimo_vision_mcp --cov-report=html
```
## 📊 性能指标
- **响应时间**：单图分析 < 3秒（取决于图片大小和网络状况）
- **并发支持**：支持多客户端同时连接
- **图片限制**：最大 40MP 像素，最大 20MB 文件大小
- **批量处理**：单次最多分析 16 张图片
## 🤝 贡献指南
欢迎贡献！请阅读我们的 [贡献指南](CONTRIBUTING.md) 了解详细的贡献流程。
### 快速贡献步骤
1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request
### 代码规范
- 使用 Python 3.11+ 语法
- 遵循 PEP 8 代码风格
- 添加类型注解
- 编写文档字符串
- 保持测试覆盖率 > 80%
更多详细信息请查看 [贡献指南](CONTRIBUTING.md)。
## 📄 许可证
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。
## 🙏 致谢
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 协议规范
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP 服务器框架
- [Xiaomi MiMo](https://mimo.xiaomi.com) - 视觉 AI 模型
## 📞 支持与反馈
- **Issues**：[GitHub Issues](https://github.com/Sunset-OrangeSea/mimo-vision-mcp/issues)
- **讨论**：[GitHub Discussions](https://github.com/Sunset-OrangeSea/mimo-vision-mcp/discussions)
- **邮箱**：---------
## 📈 更新日志
### v0.2.0 (2026-07-13)
- 新增 `MIMO_API_MODE`，支持 Token Plan 和按量 Token API
- 根据模式自动选择默认 Base URL
- 保留显式 `MIMO_BASE_URL` 覆盖和原有 Token Plan 默认行为
- 增加模式切换的兼容性测试与配置示例
### v0.1.0 (2026-07-12)
- 初始版本发布
- 支持单图、多图分析
- 支持多种分析模式
- 支持结构化数据提取
- 支持图片区域分析
- 完整的 MCP 协议支持
---
**注意**：使用本服务需要有效的 MiMo API Key。请妥善保管您的 API Key，不要将其提交到版本控制系统中。
