MiMo Vision MCP Server

A lightweight Model Context Protocol (MCP) stdio server that enables LLM agents (such as Codex CLI/Desktop, Claude Desktop) to invoke the MiMo Vision model (mimo-v2.5) for local image understanding and OCR.

---

架构流程 (Architecture)

Codex / Claude (Client)
   │ (JSON-RPC 2.0 via stdio)
   ▼
src/mimo_vision_mcp.py
   │ (curl.exe with stream base64 payload)
   ▼
https://opencode.ai/zen/go/v1/chat/completions (model: mimo-v2.5)
   │ (JSON Response)
   ▼
Recognition / Description Text returned to Client

Why curl.exe?
Some API gateways reject standard Python HTTP user agents / connection handshakes. Using native system curl.exe ensures robust connections.

---

目录结构 (Project Structure)

mimo-vision-mcp/
├── src/
│   └── mimo_vision_mcp.py    # MCP stdio 服务端核心实现（纯标准库，零三方依赖）
├── tests/
│   └── test_mcp.py           # 自动化测试脚本（生成测试图并验证协议连通性）
├── .env.example              # 环境变量配置模版
├── .gitignore                # Git 忽略配置
├── pyproject.toml            # Python 打包与元数据配置
├── LICENSE                   # MIT 开源协议
└── README.md                 # 项目文档

---

环境变量配置 (Environment Variables)

变量名	默认值	说明
MIMO_API_KEY	(必填)	MiMo / OpenCode API 密钥
MIMO_API_BASE	https://opencode.ai/zen/go/v1/chat/completions	Chat Completions 接口地址
MIMO_MODEL	mimo-v2.5	视觉模型名称
MIMO_DEFAULT_PROMPT	请详细描述这张图片的内容。	默认识别提示词
MIMO_CURL	curl.exe	用于发起 HTTP 请求的 curl 可执行程序

---

工具接口 (Tool Definition)

mimo_vision

向 MiMo 视觉模型发送本地图片，返回文字识别或描述结果。

• 参数：
  • image_path (string, 必填): 本地图片文件的绝对路径（支持 .png, .jpg, .jpeg, .webp, .gif, .bmp 等）。
  • prompt (string, 可选): 自定义提示词，如 "识别图中的文字"、"这张图里有什么物体？"。
  • model (string, 可选): 模型名称覆盖，默认 mimo-v2.5。

---

安装与接入配置 (Setup Guide)

1. Codex 接入配置 (~/.codex/config.toml)

在你的 config.toml 中添加以下配置：

[mcp_servers.mimo_vision]
type = "stdio"
command = "python"
args = ["C:\\Users\\user\\Documents\\Codex\\2026-08-17\\mimo-vision-mcp\\src\\mimo_vision_mcp.py"]
startup_timeout_sec = 120

[mcp_servers.mimo_vision.env]
MIMO_API_KEY = "your-api-key"
MIMO_API_BASE = "https://opencode.ai/zen/go/v1/chat/completions"
MIMO_MODEL = "mimo-v2.5"

2. Claude Desktop 接入配置 (claude_desktop_config.json)

{
  "mcpServers": {
    "mimo-vision": {
      "command": "python",
      "args": ["C:/Users/user/Documents/Codex/2026-08-17/mimo-vision-mcp/src/mimo_vision_mcp.py"],
      "env": {
        "MIMO_API_KEY": "your-api-key",
        "MIMO_API_BASE": "https://opencode.ai/zen/go/v1/chat/completions",
        "MIMO_MODEL": "mimo-v2.5"
      }
    }
  }
}

---

运行测试 (Testing)

$env:MIMO_API_KEY="your-api-key"
python tests/test_mcp.py

---

许可协议 (License)

本项目采用 MIT License 授权。