Vision MCP Server (TypeScript)

ローカルな Model Context Protocol サーバーは、Xiaomi の MiMo-V2.5 マルチモーダルモデルを AIエージェント向けのビジョンツールとしてラップします。

Text Agent (e.g. DeepSeek / Claude)
  → MCP Client → inspect_image tool
  → Local image sandbox + Sharp crop/scale
  → MiMo-V2.5 (vision model, Anthropic Messages API)
  → VisualObservation JSON
  → Agent continues reasoning

前提条件

• Node.js >= 20

• Xiaomi MiMo APIキー

クイックスタート

git clone https://github.com/wenren93/mimo-vision-mcp.git
cd mimo-vision-mcp
npm install
cp .env.example .env
# Edit .env and set MIMO_API_KEY
npm run build
npm run demo -- /path/to/image.png "What is in this image?"

MCPサーバーとして実行

npm run start              # STDIO mode
npm run inspect            # MCP Inspector UI

Claude との統合

claude mcp add vision \
  -e MIMO_API_KEY='your-key' \
  -e MIMO_BASE_URL='https://api.xiaomimimo.com/anthropic' \
  -e VISION_MODEL='mimo-v2.5' \
  -e VISION_ASSET_ROOT='/absolute/path/to/assets' \
  -- node /absolute/path/to/dist/server.js

📖 完全なドキュメントは下記の 中文 にあります。

中文文档 — ローカル MiMo ビジョン MCP（TypeScript）

これは OpenRouter を経由しない完全なパイプラインです：

DeepSeek V4 Pro（纯文本主 Agent，Anthropic Messages 兼容 API）
  -> MCP Client
  -> 本地 inspect_image 工具
  -> 本地图片沙箱 + Sharp 裁剪/缩放
  -> MiMo-V2.5（Anthropic Messages 兼容 API）
  -> VisualObservation JSON
  -> DeepSeek 继续推理或操作浏览器

MiMo-V2.5 はテキスト、画像、ビデオ、オーディオ入力をネイティブにサポートしているため、ここではこれをタスク条件付きの「ビジョンセンサー」としてのみ扱います。DeepSeek は引き続きプランニング、ツール呼び出し、最終回答を担当します。

プロジェクトには以下が含まれます：

• src/server.ts：STDIO Vision MCP サーバー。

• src/mimo-vision.ts：MiMo-V2.5 画像理解クライアント。

• src/demo-agent.ts：DeepSeek 公式 API + MCP ツールループの完全なデモ。

• src/add-asset.ts：ローカル画像の安全なインポート。

• src/asset-store.ts：ファイル境界、再エンコード、クロップ、座標マッピング。

• src/schemas.ts：MiMo 出力および MCP 出力の Zod Schema。

プロジェクトは MCP TypeScript SDK v2 の @modelcontextprotocol/server と @modelcontextprotocol/client を使用しており、Node.js 20 以上が必要です。MCP TypeScript SDK

1. 推奨方法：ローカル MCP + 小米 MiMo API

インストール：

cd mimo-vision-mcp
npm install
cp .env.example .env

.env を編集：

# MCP 视觉工具需要
MIMO_API_KEY=你的小米MiMo密钥
MIMO_BASE_URL=https://api.xiaomimimo.com/anthropic
VISION_MODEL=mimo-v2.5

# 仅端到端 Demo Agent 需要
DEEPSEEK_API_KEY=你的DeepSeek密钥
DEEPSEEK_BASE_URL=https://api.deepseek.com/anthropic
TEXT_MODEL=deepseek-v4-pro

VISION_ASSET_ROOT=./assets
VISION_MAX_FILE_MB=10
VISION_MAX_PIXELS=40000000
VISION_TIMEOUT_MS=45000

MiMo のリクエスト先は https://api.xiaomimimo.com/anthropic/v1/messages です。画像は Anthropic の content block を使用します：type=image、source.type=base64 で、media_type と純粋な Base64 データをそれぞれ渡します。パブリックな画像 URL は必要ありません。MiMo 画像理解；MiMo Anthropic Messages API

Related MCP server: VisionPower

2. 1コマンドで完全なパイプラインを検証

npm run demo -- /绝对路径/page.png "图中登录按钮在哪里？"

実行手順：

1. 画像は PNG に再エンコードされ、ランダムな assetId が生成されます。

2. デモがローカル MCP Server を起動し、ツール一覧を読み取ります。

3. DeepSeek V4 Pro が inspect_image の呼び出しを決定します。

4. MCP Server が管理された画像を mimo-v2.5 に送信します。

5. MiMo が OCR、視覚的証拠、正規化座標を返します。

6. Zod が出力を検証し、部分クロップ座標を元画像にマッピングし戻します。

7. DeepSeek が視覚的観察に基づいて回答を生成します。

DeepSeek 側は https://api.deepseek.com/anthropic/v1/messages を使用し、モデル ID は deepseek-v4-pro です。サードパーティのルーティングは経由しません。DeepSeek Anthropic API；DeepSeek Tool Calls

3. MCP Server を単独で実行

MCP Server 自体には MIMO_API_KEY のみが必要です：

npm run build
npm run start

MCP Inspector を使用：

npm run inspect

まずテスト画像をインポートします：

npm run add-asset -- /绝对路径/page.png

MCP Server は import_image ブリッジツールも提供しています。Claude は最初に import_image({ sourcePath }) を呼び出し、返された assetId を inspect_image に渡すことができます：

claude mcp add vision \
  -e MIMO_API_KEY='你的 MiMo API Key' \
  -e MIMO_BASE_URL='https://api.xiaomimimo.com/anthropic' \
  -e VISION_MODEL='mimo-v2.5' \
  -e VISION_ASSET_ROOT='/绝对路径/mimo-vision-mcp/assets' \
  -- node /绝对路径/mimo-vision-mcp/dist/server.js

呼び出し順序：

import_image({ sourcePath: "/你的路径/page.png" })
→ { assetId: "img_....png" }
→ inspect_image({ assetId: "img_....png", goal: "找到登录按钮" })

インポート時には PNG に再エンコードされ、VISION_ASSET_ROOT サンドボックスにコピーされます。

呼び出しパラメータ：

{
  "assetId": "img_生成的ID.png",
  "goal": "找到登录按钮并返回位置",
  "mode": "ui",
  "resolution": "auto"
}

4. 独自の Agent を接続する

mcp.config.example.json をコピーし、パスとキーを実際の値に変更します：

{
  "mcpServers": {
    "vision": {
      "command": "node",
      "args": ["/绝对路径/mimo-vision-mcp/dist/server.js"],
      "env": {
        "MIMO_API_KEY": "你的密钥",
        "MIMO_BASE_URL": "https://api.xiaomimimo.com/anthropic",
        "VISION_MODEL": "mimo-v2.5",
        "VISION_ASSET_ROOT": "/绝对路径/mimo-vision-mcp/assets"
      }
    }
  }
}

Agent Harness が Anthropic Messages を使用する場合は、src/demo-agent.ts を参照できます：

1. client.listTools() で MCP ツールを読み取ります。

2. MCP Schema を tools[].name/description/input_schema にマッピングします。

3. content[].type=tool_use を受信したら client.callTool() を実行します。

4. structuredContent をユーザーメッセージの tool_result content block に配置し、DeepSeek に返します。

5. MiMo-V2.5 の推論もローカルにデプロイする

アプリケーションと MCP 部分は引き続き TypeScript を使用します。モデル推論層には、Anthropic Messages API をサポートする vLLM を使用できます。互換サービスを起動したら、次のように変更するだけです：

MIMO_BASE_URL=http://127.0.0.1:8000
MIMO_API_KEY=local
VISION_MODEL=mimo-v2.5

vLLM は /v1/messages Anthropic 互換エンドポイントを提供しています。基本的な起動方法は以下のとおりです。実際の並列パラメータは GPU クラスターに合わせて調整する必要があります：

vllm serve XiaomiMiMo/MiMo-V2.5 \
  --served-model-name mimo-v2.5 \
  --host 127.0.0.1 \
  --port 8000 \
  --trust-remote-code \
  --reasoning-parser qwen3

MiMo-V2.5 は、総パラメータ 310B、アクティブパラメータ 15B の FP8 MoE です。15B はトークンごとのアクティブ量にすぎず、15B の重みだけを読み込めばよいという意味ではありません。一般的なパソコンでは元のモデルを実用的に実行できません。公式の参考デプロイでは、複数 GPU の並列処理を採用しています。MiMo-V2.5 モデルカードとデプロイ；vLLM Anthropic Messages API

こうすることで画像はローカルマシンの外に出ません。ただし、サンプル内の DeepSeek メイン Agent は依然として DeepSeek 公式 API を呼び出します。パイプライン全体を完全にオフラインにする必要がある場合は、メインのテキストモデルも別途セルフホストする必要があります。

6. ブラウザスクリーンショットの連携

ブラウザ実行エージェントは現在の viewport のスクリーンショットを VISION_ASSET_ROOT に書き込みます：

const assetId = `shot_${crypto.randomUUID()}.png`;
await page.screenshot({
  path: path.join(process.env.VISION_ASSET_ROOT!, assetId),
  fullPage: false,
});

inspect_image は 0..1 の座標を返します。中心点をクリックします：

const clickX = (box.x + box.width / 2) * viewport.width;
const clickY = (box.y + box.height / 2) * viewport.height;
await page.mouse.click(clickX, clickY);

依然として DOM/Accessibility Tree を優先し、視覚情報はフォールバックとして使用することを推奨します。クリックする前に再スクリーンショットを撮り、スクロール、アニメーション、ポップアップによって座標が無効にならないようにしてください。

7. JSON 出力とセキュリティ境界

MiMo の Anthropic 互換ドキュメントは現在、response_format や厳密な JSON Schema パラメータを宣言していないため、このプロジェクトでは OpenAI 専用のフィールドを送信せず、次の方法を採用しています：システムプロンプトで純粋な JSON を要求し、プロンプト内に Schema を組み込み、JSON を解析し、Zod で厳格に検証します。不適合な結果は直接失敗となり、半構造化テキストをメイン Agent に渡しません。

• MCP パラメータは assetId のみを受け入れ、任意の URL や絶対パスは受け入れません。

• 画像は VISION_ASSET_ROOT からのみ読み取れます。インポート時に再エンコードされ、メタデータが除去されます。

• ファイルサイズと最大ピクセル数を制限し、画像爆弾（デコンボンバー）のリスクを低減します。

• 画像内のテキストは信頼できないデータとして扱われ、Agent の指示としては使用できません。

• STDIO の stdout は MCP JSON-RPC チャネルです。ログは stderr にのみ書き込めます。

8. 開発

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 类型检查
npm run typecheck

# 代码检查
npm run lint
npm run lint:fix

# 代码格式化
npm run format
npm run format:check

# 运行测试
npm test

テストは外部モデルを呼び出さず、画像インポート、クロップマッピング、実際の STDIO MCP ハンドシェイクを検証します。本番公開前に、中国語 OCR、Web UI、ぼやけたスクリーンショット、チャート、画像プロンプトインジェクションの回帰サンプルを追加することをお勧めします。

9. コントリビューション

コントリビューションを歓迎します！詳細は CONTRIBUTING.md をお読みください。

10. ライセンス

このプロジェクトは MIT ライセンス を採用しています。