mimo-vision-mcp

Dale capacidad de visión a los LLM solo de texto a través de MCP, impulsado por modelos de visión como Xiaomi MiMo-V2.5.

A través de MCP (Model Context Protocol), se expone la capacidad de comprensión de imágenes de modelos de visión (como MiMo-V2.5 de Xiaomi) a LLM de texto que no poseen capacidades multimodales. Cuando el modelo de texto se encuentra con imágenes/capturas de pantalla/rutas de imagen, puede llamar activamente a herramientas como analyze_image, describe_image, extract_text_from_image para obtener capacidades de visión.

🚀 Inicio con un clic (los principiantes pueden empezar en 1 minuto, sin necesidad de escribir ningún comando)

Este proyecto incluye un inicio con un clic vía WebUI, todo con operaciones de ratón, configuración automática del entorno, sin necesidad de línea de comandos:

1. Descarga / clona este proyecto en tu máquina local

2. Haz doble clic en start-webui.bat (Windows): el script creará automáticamente .env (a partir de .env.example), instalará el entorno/dependencias, iniciará el servicio y abrirá el navegador automáticamente

3. Una vez abierto el navegador, introduce tu API Key en la página web → haz clic en «Aplicar a CLI», o simplemente arrastra una imagen → elige un modelo de visión → haz clic en «Prueba de vista previa» para ver al modelo de visión "describir la imagen"

En el primer inicio se instalarán las dependencias automáticamente (requiere conexión a internet, unos 1~2 minutos); después, con doble clic se abre al instante. No necesitas saber Python, ni escribir pip a mano, ni crear .env manualmente: el script lo hace todo automáticamente.

La integración completa de la capacidad de visión del LLM de texto en la línea de comandos se describe a continuación en Integración con opencode.

Related MCP server: mimo-vision-mcp

Principio

El modelo de texto se encarga de la "orquestación", el modelo de visión se encarga de "ver", y MCP es la interfaz que conecta ambos: los datos de imagen no pasan por el modelo de texto.

用户给图片路径/URL
  → ① 文本 LLM 根据工具列表 + 调用指引，决定调用 analyze_image
  → ② opencode / 任意 MCP 客户端（stdio）
  → ③ mimo-vision MCP server（图片归一化 + 转发请求）
  → ④ 视觉模型（MiMo-V2.5 等，经 OpenCode Go / 自定义供应商）真正"看"图
  → ⑤ 文本结果原路返回，文本模型转述给用户

Características

• Inicio con un clic: haz doble clic en start-webui.bat y listo; instala dependencias, inicia el servicio y abre el navegador automáticamente, sin barreras para principiantes

• Listo para usar: integra OpenCode Go por defecto; solo necesitas una API Key para empezar, y también puedes cambiar al proveedor oficial de Xiaomi o a cualquier proveedor personalizado

• Basado en el protocolo compatible con OpenAI, transporte local stdio, compatible con cualquier cliente MCP como opencode / Claude Desktop / Cursor

• Entrada de imágenes flexible: ruta local / URL http(s) / data URI base64 / base64 puro son todos válidos

• Soporta múltiples imágenes, detección automática de formato (JPEG/PNG/GIF/WebP/BMP), validación del límite de 50MB

• Selección automática del protocolo de API según el modelo: gpt-*/grok-* usan Responses API, el resto usa chat/completions (se puede forzar)

• WebUI integrado como panel de configuración: selección visual de modelos, prueba de vista previa, sincronización con CLI sin reiniciar

• Mensajes de error amigables si no hay API key, sin fallos

Estructura de directorios

mimo-vision-mcp/
├── mimo_vision_mcp/
│   ├── config.py           # 配置读取（.env 实时重读）+ 应用到 MCP
│   ├── image_loader.py     # 图片输入归一化 + MIME 探测
│   ├── providers.py        # 供应商注册表 + call_vision（chat/responses 适配）
│   └── server.py           # FastMCP server + 3 个工具
├── webui/                  # WebUI 配置面板（FastAPI + 单页 HTML）
├── tests/                  # 单元测试
├── .github/workflows/ci.yml
├── opencode.example.json   # opencode 接入配置示例
├── AGENTS.md               # 文本模型的调用指引
├── start-webui.bat           # 🚀 一键启动（Windows，双击即用）
├── LICENSE
└── pyproject.toml

Instalación

python -m venv .venv
# Windows: .\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.venv/bin/python -m pip install -e ".[dev]"

Configuración de la API Key

Este proyecto usa por defecto el plan OpenCode Go para llamar a MiMo-V2.5 (modelo mimo-v2.5, endpoint compatible con OpenAI https://opencode.ai/zen/go/v1).

1. Suscríbete a Go en opencode.ai/auth y copia la API Key

2. Copia .env.example a .env y rellénalo:

   MIMO_API_KEY=你的-opencode-go-key

También se puede sobrescribir mediante variables de entorno (config.py relee .env en cada llamada):

Cambiar el modelo de visión: en OpenCode Go, los modelos multimodales más rápidos se pueden configurar cambiando MIMO_MODEL a gpt-5.6-luna (usa /responses) o minimax-m3. Ten en cuenta que mimo-v2.5-pro es un modelo solo de texto y no puede ver imágenes.

Ejecutar el servidor MCP

# 方式一：控制台脚本
mimo-vision-mcp
# 方式二：模块运行
python -m mimo_vision_mcp.server

Integración con opencode

Consulta opencode.example.json para registrar mimo-vision como servidor MCP stdio local:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mimo-vision": {
      "type": "local",
      "command": ["<你的python路径>", "-m", "mimo_vision_mcp.server"],
      "enabled": true,
      "environment": { "MIMO_API_KEY": "{env:MIMO_API_KEY}" }
    }
  },
  "experimental": { "mcp_timeout": 120000 }
}

Nota: experimental.mcp_timeout (por defecto 30s) controla el tiempo de espera de las llamadas a herramientas MCP. Las solicitudes de visión pueden tardar decenas de segundos, así que ajústalo a más de 120s; no configures timeout por separado en mcp.mimo-vision, ya que sobrescribiría mcp_timeout y provocaría tiempos de espera. Después de cambiar la configuración, reinicia opencode para que surta efecto.

Este proyecto también incluye AGENTS.md (guía de llamadas para el modelo de texto), que se puede inyectar en cada sesión mediante la configuración global "instructions": ["<ruta>/AGENTS.md"], para que el modelo de texto puro llame activamente a las herramientas cuando encuentre imágenes.

Descripción de herramientas

Cada elemento de images admite:

• Ruta absoluta local: C:/Users/xx/Pictures/a.png

• URL pública: https://example.com/a.jpg

• data URI base64: data:image/png;base64,....

• Cadena base64 pura

Devuelve JSON: { "result": "...", "error": "", "model": "...", "usage": {...} }

WebUI (frontend interactivo · inicio con un clic)

Entrada recomendada para principiantes: interfaz gráfica, sube imágenes, elige modelo, ve los resultados, todo con el ratón.

Inicio con un clic (lo más sencillo, sin necesidad de comandos)

Haz doble clic en start-webui.bat (Windows):

1. El script comprueba/crea el entorno automáticamente e instala las dependencias

2. Inicia el servicio automáticamente y abre el navegador

3. Si el servicio ya está en ejecución, solo abre el navegador, sin iniciar duplicados

Para usuarios que no usan Windows, inicio manual: python -m pip install -e ".[web]" && python -m webui.app, y luego abre http://127.0.0.1:8000 en el navegador (el puerto se puede cambiar con MIMO_WEBUI_PORT).

Funciones de la interfaz

• La parte superior «Modelo activo CLI / MCP» muestra el proveedor/modelo/estilo que usa realmente el LLM de línea de comandos

• Después de elegir el modelo, haz clic en «Aplicar a CLI (sincronizar con MCP)»; la configuración se escribe en .env, sin reiniciar, y la próxima llamada del CLI usará el nuevo modelo

• La parte inferior «Prueba de vista previa (no afecta al CLI)» sirve para probar el resultado primero

• La API Key se guarda en el localStorage del navegador; al hacer clic en «Aplicar a CLI» también se puede escribir en .env

Pruebas

python -m pytest -q

Preguntas frecuentes

• ¿No sé programar / no quiero escribir comandos?: haz doble clic en start-webui.bat; el script creará .env, instalará dependencias, iniciará el servicio y abrirá el navegador automáticamente, todo con el ratón

• ¿Dónde se rellena la API Key?: después de clonar no hay .env (el repositorio solo contiene la plantilla vacía .env.example). Al hacer doble clic en el script de inicio se genera .env automáticamente; luego rellena la Key en la página web y haz clic en «Aplicar a CLI», o edita directamente MIMO_API_KEY en .env

• Devuelve "API Key no configurada": configura MIMO_API_KEY en .env (o rellénala directamente en el WebUI y haz clic en «Aplicar a CLI»)

• Formato de imagen no compatible: solo se admiten JPEG/PNG/GIF/WebP/BMP

• Error "no se puede analizar" con entrada base64: asegúrate de que la entrada sea base64 válido y que el formato esté dentro de los admitidos

• Tiempo de espera agotado en llamadas a herramientas MCP: ajusta experimental.mcp_timeout a más de 120000ms

Licencia

MIT

Referencias

• Documentación de OpenCode Go

• Documentación de la API de Xiaomi MiMo

• Guía de comprensión de imágenes