mimo-vision-mcp

MCP を介して、Xiaomi MiMo-V2.5 などのビジョンモデルを利用し、テキストのみの LLM に視覚能力を提供します。

MCP（Model Context Protocol） を通じて、ビジョンモデル（Xiaomi MiMo-V2.5 など）の画像理解能力を、マルチモーダル機能を持たないテキスト LLM に公開します。テキストモデルは画像・スクリーンショット・画像パスに遭遇した際、analyze_image、describe_image、extract_text_from_image などのツールを積極的に呼び出して視覚能力を獲得できます。

🚀 ワンクリック起動（初心者でも 1 分で開始、コマンド入力不要）

このプロジェクトには WebUI ワンクリック起動 が組み込まれており、すべてマウス操作で完了し、すべての環境設定が自動で行われます。コマンドラインの知識は一切不要です：

1. 本プロジェクトをダウンロード / クローンします

2. start-webui.bat をダブルクリック（Windows）— スクリプトが自動的に .env を作成（.env.example から）、環境/依存関係を自動インストール、サービスを起動し、ブラウザを自動的に開きます

3. ブラウザが開いたら、Web ページでAPI Key を入力 → 「CLI に適用」をクリック、または画像を直接ドラッグ＆ドロップ → ビジョンモデルを選択 → 「プレビューテスト」をクリックすると、ビジョンモデルが「画像を見て説明する」様子を確認できます

初回起動時は依存関係のインストールが自動で行われます（ネット接続が必要、約 1〜2 分）。以降はダブルクリックですぐに起動します。 Python の知識は一切不要、pip を手入力する必要も、.env を手動で作成する必要もありません — スクリプトがすべて自動で行います。

コマンドラインのテキスト LLM が視覚能力を使用するための完全な接続方法は、下記の opencode への接続 を参照してください。

Related MCP server: mimo-vision-mcp

原理

テキストモデルが「スケジューリング」を担当し、ビジョンモデルが「見る」ことを担当します。MCP は両者を接続するインターフェースです — 画像データ自体はテキストモデルを経由しません。

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

特徴

• ワンクリック起動：start-webui.bat をダブルクリックするだけで、依存関係の自動インストール、サービス起動、ブラウザ起動が行われ、初心者でもゼロから始められます

• すぐに使える：デフォルトで OpenCode Go に接続され、API Key を 1 つ入力するだけで開始できます。Xiaomi 公式 / 任意のカスタムプロバイダーにも切り替え可能

• OpenAI 互換プロトコルに基づき、stdio ローカル転送で、opencode / Claude Desktop / Cursor などの任意の MCP クライアントに接続可能

• 画像入力は柔軟：ローカルパス / http(s) URL / base64 data URI / 純粋な base64 すべて対応

• 複数画像入力対応、画像形式の自動認識（JPEG/PNG/GIF/WebP/BMP）、50MB 制限の検証

• モデルに応じて API プロトコルを自動選択：gpt-*/grok-* は Responses API、それ以外は chat/completions（強制指定可能）

• 内蔵 WebUI 設定パネル：視覚的にモデル選択、プレビューテスト、選択すると CLI に同期され、再起動不要

• API key がない場合は親切なエラーメッセージを返し、クラッシュしません

ディレクトリ構造

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

インストール

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

API Key の設定

このプロジェクトはデフォルトで OpenCode Go プランを使用して MiMo-V2.5（モデル mimo-v2.5、OpenAI 互換エンドポイント https://opencode.ai/zen/go/v1）を呼び出します。

1. opencode.ai/auth で Go を購読し、API Key をコピーします

2. .env.example を .env にコピーして記入します：

   MIMO_API_KEY=你的-opencode-go-key

環境変数による上書きも可能です（config.py は呼び出しのたびに .env をリアルタイムで再読み込みします）：

ビジョンモデルの切り替え：OpenCode Go のより高速なマルチモーダルモデルを使用する場合、MIMO_MODEL を gpt-5.6-luna（/responses 経由）または minimax-m3 に変更できます。mimo-v2.5-pro はテキストのみのモデルで、画像を見ることはできません。

MCP server の実行

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

opencode への接続

opencode.example.json を参照して、mimo-vision をローカル stdio MCP server として登録します：

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

注意：experimental.mcp_timeout（デフォルト 30 秒）が MCP ツール呼び出しのタイムアウトを制御します。ビジョンリクエストは数十秒かかる場合があるため、120 秒以上に調整する必要があります。mcp.mimo-vision 内で個別に timeout を設定しないでください。mcp_timeout を上書きしてタイムアウトの原因になります。設定変更後は opencode を再起動する必要があります。

このプロジェクトには AGENTS.md（テキストモデル向けの呼び出しガイド）も同梱されており、グローバル設定 "instructions": ["<パス>/AGENTS.md"] で各セッションに注入でき、テキストのみのモデルが画像に遭遇したときにツールを積極的に呼び出すようにできます。

ツールの説明

images の各項目は以下に対応：

• ローカル絶対パス：C:/Users/xx/Pictures/a.png

• 公開 URL：https://example.com/a.jpg

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

• 純粋な base64 文字列

JSON を返します：{ "result": "...", "error": "", "model": "...", "usage": {...} }

WebUI（対話型フロントエンド・ワンクリック起動）

初心者向けの最初の入り口：グラフィカルインターフェースで、画像アップロード、モデル選択、効果確認がすべてマウス操作で行えます。

ワンクリック起動（最も簡単、コマンド不要）

start-webui.bat をダブルクリック（Windows）するだけです：

1. スクリプトが環境のチェック/作成、依存関係の自動インストールを実行

2. サービスを自動起動し、ブラウザを自動的に開きます

3. サービスが既に実行中の場合はブラウザを直接開き、重複起動しません

Windows 以外のユーザーは手動で起動：python -m pip install -e ".[web]" && python -m webui.app、その後ブラウザで http://127.0.0.1:8000 を開きます（ポートは MIMO_WEBUI_PORT で変更可能）。

インターフェース機能

• 上部の「CLI / MCP 現在有効なモデル」に、コマンドライン LLM が実際に使用するプロバイダー/モデル/スタイルが表示されます

• モデルを選択後、「CLI に適用（MCP に同期）」 をクリックすると、設定が .env に書き込まれ、再起動不要で、CLI の次回呼び出しから新しいモデルが使用されます

• 下部の「プレビューテスト（CLI に影響なし）」で先に効果を試せます

• API Key はブラウザの localStorage に保存されます。「CLI に適用」時に .env にも書き込めます

テスト

python -m pytest -q

よくある質問

• プログラミングができない / コマンドを入力したくない場合：start-webui.bat をダブルクリックするだけです。スクリプトが自動的に .env を作成し、依存関係をインストールし、サービスを起動し、ブラウザを開きます。すべてマウス操作です

• API Key はどこに入力する？：クローン後は .env がありません（リポジトリには空のテンプレート .env.example のみ）。起動スクリプトをダブルクリックすると自動的に .env が生成され、その後 Web ページで Key を入力して「CLI に適用」をクリックするか、.env の MIMO_API_KEY を直接編集します

• 「API Key が設定されていません」と表示される：.env に MIMO_API_KEY を設定します（または WebUI で直接入力して「CLI に適用」）

• 画像形式がサポートされていない：JPEG/PNG/GIF/WebP/BMP のみ対応

• base64 入力で「解析できません」エラー：入力が有効な base64 であり、形式がサポート範囲内であることを確認してください

• MCP ツール呼び出しのタイムアウト：experimental.mcp_timeout を 120000ms 以上に調整してください

ライセンス

MIT

参考

• OpenCode Go ドキュメント

• Xiaomi MiMo API ドキュメント

• 画像理解ガイド