Content
# MiMo Vision MCP
[English](README_EN.md) | [English](README_EN.md)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
> A local visual service based on Model Context Protocol (MCP), providing powerful image analysis capabilities for AI clients like Codex, Claude Desktop, GitHub Copilot, etc.
## ✨ Features
### Core Capabilities
- **Multi-Image Analysis**: Supports single image, multi-image (up to 16 images), and image comparison analysis
- **Multi-Source Input**: Supports local image paths, public image URLs, and Base64 encoded images
- **Intelligent Modes**: General recognition, OCR, screenshot analysis, flowchart layout checking, and structured JSON extraction
- **Region Analysis**: Supports cropping a specified region for secondary recognition analysis
- **Depth Control**: Allows control over MiMo's deep thinking mode and maximum output token count
- **Dual Access Modes**: Supports Token Plan and pay-as-you-go Token API, with default Token Plan
### Toolset
| Tool | Description | Applicable Scenarios |
| ------------------------ | ------------------------ | ---------------------- |
| `analyze_image` | Single image general analysis | Quick image recognition |
| `analyze_images` | Multi-image analysis (supports multiple modes) | Batch image processing, comparison analysis |
| `compare_images` | Multi-image difference and common point comparison | Version comparison, difference detection |
| `check_layout` | Flowchart/diagram layout checking | UI/UX design review |
| `extract_image_data` | Structured JSON data extraction | Data processing, automation pipeline |
| `find_images` | Find images within an allowed directory | File management, batch processing |
| `get_image_metadata` | Read image metadata | File information retrieval |
| `inspect_image_region` | Crop region secondary recognition | Detail analysis, local zoom |
## 🚀 Quick Start
### Environment Requirements
- Python 3.11 or higher
- MiMo API Key ([apply here](https://mimo.xiaomi.com))
### Installation
```bash
# Clone the project
git clone https://github.com/Sunset-OrangeSea/mimo-vision-mcp.git
cd mimo-vision-mcp
# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
# Windows
.\.venv\Scripts\Activate.ps1
# Linux/macOS
source .venv/bin/activate
# Install the project
pip install -e ".[dev]"
```
### Configuration
Create a `.env.local` file (do not commit to Git):
```bash
# Required configuration
MIMO_API_KEY=your_api_key_here
# Optional configurations (default values shown)
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` supports two values:
- `token_plan`: Token Plan, using `tp-...` Key; default address is `https://token-plan-cn.xiaomimimo.com/v1`.
- `token_api`: Pay-as-you-go Token API, using `sk-...` Key; default address is `https://api.xiaomimimo.com/v1`.
When choosing `token_api`, you can omit `MIMO_BASE_URL`, and the service will automatically use the corresponding default address; explicitly setting `MIMO_BASE_URL` takes precedence. The two types of keys are independent and cannot be mixed.
#### Token Plan Configuration
```dotenv
MIMO_API_MODE=token_plan
MIMO_API_KEY=tp-your-token-plan-key
```
#### Token API Configuration
```dotenv
MIMO_API_MODE=token_api
MIMO_API_KEY=sk-your-token-api-key
```
Unless you need a regional node or custom proxy, you don't need to fill in `MIMO_BASE_URL` additionally. After modifying the mode, only newly started MCP processes will read the new configuration; already running processes will keep the original configuration and will not be actively restarted by this project.
### Run
```bash
# Start the MCP service
python -m mimo_vision_mcp
# Or use the installed command
mimo-vision-mcp
```
## 📦 Client Configuration
### Codex
Refer to `examples/codex-config.toml`, or add to the user-level configuration `C:\Users\<username>\.codex\config.toml`:
```toml
[mcp.mimo-vision]
command = "python"
args = ["-m", "mimo_vision_mcp"]
```
### Claude Desktop
Refer to `examples/claude_desktop_config.json`, and add to the Claude Desktop configuration:
```json
{
"mcpServers": {
"mimo-vision": {
"command": "python",
"args": ["-m", "mimo_vision_mcp"]
}
}
}
```
### GitHub Copilot
Refer to `examples/copilot-mcp-config.json` and configure the MCP server.
## 🧪 Testing and Verification
```bash
# Set the Python path
export PYTHONPATH=$(pwd)/src # Linux/macOS
$env:PYTHONPATH = (Join-Path (Get-Location) "src") # Windows PowerShell
# Run tests
python -m pytest -q
# Code compilation check
python -m compileall -q src tests
# Code style check
python -m ruff check .
# MCP protocol verification (no API Key required)
python scripts/probe_mcp.py
# Full functional test (requires API Key)
python scripts/smoke_test_mimo_vision.py
```
## 📁 Project Structure
```
mimo-vision-mcp/
├── docs/ # Documentation directory
│ └── superpowers/
│ ├── plans/ # Development plans
│ └── specs/ # Technical specifications
├── examples/ # Configuration examples
│ ├── claude_desktop_config.json
│ ├── codex-config.toml
│ └── copilot-mcp-config.json
├── scripts/ # Tool scripts
│ ├── probe_mcp.py # MCP protocol verification
│ └── smoke_test_mimo_vision.py # Functional test
├── src/ # Source code
│ └── mimo_vision_mcp/
│ ├── __init__.py
│ ├── __main__.py # Program entry
│ ├── config.py # Configuration management
│ ├── image_input.py # Image input processing
│ ├── provider.py # MiMo API call
│ └── server.py # MCP server implementation
├── tests/ # Test code
│ ├── test_config.py
│ ├── test_image_input.py
│ ├── test_image_tools.py
│ ├── test_mcp_protocol.py
│ ├── test_provider.py
│ └── test_server.py
├── .gitignore
├── CHANGELOG.md # Update log
├── CONTRIBUTING.md # Contribution guide
├── LICENSE # MIT license
├── pyproject.toml # Project configuration
├── README.md # English documentation
└── README_EN.md # English documentation
```
## 🔧 Development Guide
### Development Environment Setup
```bash
# Install development dependencies
pip install -e ".[dev]"
# Code formatting
black src tests
# Code check
ruff check src tests
```
### Add New Tools
1. Define the tool function in `src/mimo_vision_mcp/server.py`
2. Register the tool using the `@mcp.tool()` decorator
3. Add corresponding test cases
4. Update the README documentation
### Test Coverage
```bash
# Run tests and generate coverage report
python -m pytest --cov=mimo_vision_mcp --cov-report=html
```
## 📊 Performance Metrics
- **Response Time**: Single image analysis < 3 seconds (depends on image size and network conditions)
- **Concurrency Support**: Supports multiple clients connected simultaneously
- **Image Limit**: Maximum 40MP pixels, maximum 20MB file size
- **Batch Processing**: Up to 16 images analyzed at once
## 🤝 Contribution Guide
Contributions are welcome! Read our [Contribution Guide](CONTRIBUTING.md) for detailed contribution processes.
### Quick Contribution Steps
1. Fork the project
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Create a Pull Request
### Code Style
- Use Python 3.11+ syntax
- Follow PEP 8 code style
- Add type annotations
- Write docstrings
- Keep test coverage > 80%
For more details, see [Contribution Guide](CONTRIBUTING.md).
## 📄 License
This project uses the MIT license - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgements
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP protocol specification
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [Xiaomi MiMo](https://mimo.xiaomi.com) - Visual AI model
## 📞 Support and Feedback
- **Issues**: [GitHub Issues](https://github.com/Sunset-OrangeSea/mimo-vision-mcp/issues)
- **Discussion**: [GitHub Discussions](https://github.com/Sunset-OrangeSea/mimo-vision-mcp/discussions)
- **Email**: ---------
## 📈 Update Log
### v0.2.0 (2026-07-13)
- Added `MIMO_API_MODE`, supporting Token Plan and pay-as-you-go Token API
- Automatically select default Base URL based on the mode
- Retain explicit `MIMO_BASE_URL` override and original Token Plan default behavior
- Increased compatibility testing and configuration examples for mode switching
### v0.1.0 (2026-07-12)
- Initial version release
- Supports single image, multi-image analysis
- Supports multiple analysis modes
- Supports structured data extraction
- Supports image region analysis
- Complete MCP protocol support
**Note**: Using this service requires a valid MiMo API Key. Please keep your API Key secure and do not submit it to version control systems.
