mimo-vision-mcp

Gib textbasierten LLMs eine visuelle Wahrnehmung über MCP – unterstützt von Vision-Modellen wie Xiaomi MiMo-V2.5.

Über das MCP (Model Context Protocol) wird die Bildverständnisfähigkeit von Vision-Modellen (z. B. Xiaomi MiMo-V2.5) für textbasierte LLMs ohne multimodale Fähigkeiten verfügbar gemacht. Wenn das Textmodell auf Bilder/Screenshots/Bildpfade trifft, kann es selbstständig Tools wie analyze_image, describe_image und extract_text_from_image aufrufen, um eine visuelle Antwort zu erhalten.

🚀 Ein-Klick-Start (auch für Anfänger: in 1 Minute einsatzbereit, ganz ohne Befehle)

Dieses Projekt enthält einen eingebauten WebUI-Ein-Klick-Start – alles läuft über die Maus, die komplette Umgebungskonfiguration wird automatisch erledigt, ganz ohne Befehlszeilen-Hürden:

1. Lade das Projekt herunter bzw. klone es auf deinen Rechner.

2. Doppelklicke start-webui.bat (Windows) – das Skript erstellt automatisch .env (aus .env.example), richtet Umgebung/Abhängigkeiten ein, startet den Dienst und öffnet automatisch den Browser.

3. Wenn der Browser offen ist, trage deinen API Key ein → klicke auf „Auf CLI anwenden", oder ziehe einfach ein Bild hinein → wähle ein Vision-Modell aus → klicke auf „Vorschau/Test“, und du siehst, wie das Vision-Modell „erzählt, was es sieht“.

Beim ersten Start werden die Abhängigkeiten automatisch installiert (Internet erforderlich, ca. 1–2 Minuten). Danach genügt ein Doppelklick und es startet sofort. Du brauchst kein Python zu verstehen, kein pip von Hand einzutippen und keine .env manuell anzulegen – das Skript übernimmt alles automatisch.

Die vollständige Anbindung, damit ein Text-LLM in der Befehlszeile Vision-Fähigkeiten nutzen kann, findest du unten unter opencode einbinden.

Related MCP server: mimo-vision-mcp

Wie es funktioniert

Das Textmodell übernimmt die „Steuerung“, das Vision-Modell das „Sehen“ – MCP ist die Schnittstelle, die beide verbindet. Die Bilddaten selbst laufen dabei nicht durch das Textmodell.

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

Eigenschaften

• Ein-Klick-Start: Ein Doppelklick auf start-webui.bat genügt – Abhängigkeiten werden automatisch installiert, Dienst gestartet, Browser geöffnet. Für Anfänger ohne Hürden.

• Sofort einsatzbereit: Standardmäßig ist OpenCode Go angebunden – einen API Key eintragen und es geht los. Es kann auch auf Xiaomi offiziell / einen beliebigen eigenen Anbieter umgestellt werden.

• Basiert auf het OpenAI-kompatible Protokoll, stdio-Transport lokal, funktioniert mit beliebigen MCP-Clients wie opencode, Claude Desktop, Cursor usw.

• Flexible Bildeingaben: lokale Pfade / http(s)-URLs / base64 data URI / reines base64 werden unterstützt.

• Unterstützt mehrere Bilder, automatische Formaterkennung (JPEG/PNG/GIF/WebP/BMP) und prüft das 50-MB-Limit.

• Wählt das API-Protokoll automatisch passend zum Modell aus: gpt-*/grok-** werden über die Responses API ausgeführt, der Rest über chat/completions (auch erzwingbar).

• Integriertes WebUI-Panel: Model visual auswählen, Vorschau testen – die Auswahl wird sofort in die CLI übernommen, kein Neustart nötig.

• Ohne API Key gibt es eine verständliche Fehlermeldung statt eines Absturzes.

Verzeichnisstruktur

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

Installation

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

API-Key konfigurieren

Dieses Projekt nutzt standardmäßig das OpenCode-Go-Angebot für MiMo-V2.5 (Modell mimo-v2.5, OpenAI-kompatibler Endpoint https://opencode.ai/zen/go/v1).

1. Abonniere Go auf opencode.ai/auth und kopiere dir den API Key.

2. Kopiere .env.example nach .env und trage Folgendes ein:

MIMO_API_KEY=你的-opencode-go-key

Die Werte lassen sich auch über Umgebungsvariablen überschreiben (config.py liest .env bei jedem Aufruf neu):

Vision-Modell wechseln: Für schnellere, multimodale Modelle aus OpenCode Go kannst du MIMO_MODEL auf gpt-5.6-luna (nutzt /responses) oder minimax-m3 umstellen. Beachte: mimo-v2.5-pro ist ein reines Text-Modell und kann keine Bilder sehen.

MCP-Server ausführen

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

opencode einbinden

Regestrer mimo-vision als lokalen stdio-MCP-Server – siehe opencode.example.json:

{
  "$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 }
}

Hinweis: experimental.mcp_timeout (Standard: 30 s) steuert das Zeitlimit für MCP-Toolaufrufe. Bildverarbeitung kann mehrere zehn Sekunden dauern; setze deshalb auf über 120 s. Setze nicht zusätzlich timeout in mcp.mimo-vision – das überschreibt mcp_timeout und führt zu einem Timeout. Nach Änderungen muss opencode neu gestartet werden.

The project also has inclued AGENTS.md (Anleitung zur Nutzung für das Textmodell) – die kannst du per globaler Konfiguration "instructions": ["<Pfad>/AGENTS.md"] in jede Sitzung injizieren, sodass das Textmodell bei Bilderkennung automatisch die Tools aufruft.

Tool-Übersicht

images-Einträge können sein:

• lokale absolute Pfad: C:/Users/xx/Bilders/a.png

• Öffentliche URL: https://example.com/a.jpg

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

• reines base64 als String.

Die Ausgabe ist JSON: { "result": "...", "error": "", "model": "...", "usage": {...} }

WebUI (interaktive Oberfläche · Ein-Klick-Start)

Die bevorzugte Ein-Erst-Einstieg für Anfänger: Grafisches Bedienfurface für Bild, Modellwahl und Ergebnisaussicht – alles mit der Maus.

Ein-Klick-Start (am einfachsten, keine Vorkenntnisse nötig)

Doppelklick auf start-webui.bat (Windows) genügt:

1. Das Skript prüft/erstellt die Umgebung automatisch, installiert Abhängigkeiten automatisch.

2. Startet den Dienst automatisch und stände automatisch den Browser.

3. Läuft der Webserver bereits, wird nur der Browser geöffnet, kein Doppelstart.

Nicht-Windows-Nutzer starten manuell: python -m pip install -e ".[web]" && python -m webui.app und dann im Browser http://127.0.0.1:8000 öffnen (Port über MIMO_WEBUI_PORT änderbar).

Oberflächenfunktionen

• Oben zeigt „CLI / MCP aktuell aktives Modell“ den vom Kommandozeilen-LLM tatsächlich verwendeten Anbieter/Modell/Stil.

• Nach Modellwahl klick „Auf CLI anwenden (mit MCP synchronisieren)“ – die Konfiguration wird in .env geschrieben, kein Neustart nötig; der nächste CLI-Aufruf nutzt das neue Modell.

• Die „Vorschau/Test“** Bereich (ändert nichts an der CLI)** dient zum Ausprobieren.

• Der API Key wird im browser’s localStorage gespeichert; bei „Auf CLI anwenden“ kann er zugleich in .env übernommen werden.

Testen

python -m pytest -q

Häufige Fragen (FAQ)

• Ich kann nicht programmieren / will keine Befehle tippen. Genügend!: Genügt ein Doppelklick auf start-webui.bat; automatisch werden .env erstellt, Dependencies installiert, Dienst gestartet und Browser geöffnet – komplett per Maus.

• Wo trage ich den API Key ein? Nach dem Klonen existiert keine .env (nur die leere Vorlage .env.example). Der Doppelklick erzeugt .env automatisch; danach Key im Webformular füllen und „Auf CLI anwenden“ klicken, oder direkt MIMO_API_KEY in der .env editieren.

• Fehlermeldung „API-Key nicht konfiguriert“: Setze MIMO_API_KEY in der .env (oder trage ihn direkt im WebUI ein und klicke auf „Auf CLI anwenden“).

• Bildformat wird nicht unterstützt: Unterstützt werden nur JPEG/PNG/GIF/WebP/BMP.

• base64 input zeigt „unübersetzbar“: Achte darauf, dass die Eingabe gültiges Base64 ist und das Format zum unterstützter Bereich gehört.

• MCP-Toolaufruf löst Timeout aus: Setze experimental.mcp_timeout auf mehr als 120000 ms (120 s).

License

MIT

Referenzen

• OpenCode Go Dokumentation

• Xiaomi MiMo API Dokumentation

• Leitfaden Bildverständnis