Claude Code に「目」を与える — ローカル VLM で画像・動画をコンテキスト消費ゼロで理解させる

@ShadeLurk 氏が X で公開した記事が注目を集めています。

Claude Code に「目」を作る — コンテキストを 1 トークンも使わずに動画を理解させる方法

Claude Code で画像や動画を扱うと、1 枚あたり数千トークンがコンテキストから消えます。ローカル VLM（Qwen3-VL 等）を MCP サーバー経由で接続し、画像処理をオフロードすることで、Claude Code のコンテキストを一切消費せずにビジュアル情報を扱う手法が提案されています。本記事では、この問題の構造と解決アプローチを技術的に解説します。

問題 — 画像 1 枚で数千トークンが消える

Claude のビジョン処理とトークン消費

Claude API でのビジョン処理は、画像をトークンに変換してコンテキストウィンドウに載せる仕組みです。Anthropic の公式ドキュメントによると、トークン消費量は以下の式で算出されます。

tokens = (width px × height px) / 750

1 枚の高解像度スクリーンショットで 約 1,600 トークンが消費されます。Claude Code のコンテキストウィンドウは約 200,000 トークンですが、システムプロンプト・CLAUDE.md・会話履歴・MCP ツール定義などが既に占有しているため、実質的に使える容量は限られています。

動画の場合はさらに深刻

動画を Claude Code で扱う場合、フレームを抽出して画像として送信する必要があります。30 秒の動画から 1 秒ごとにフレームを抽出すると 30 枚。1 枚 1,600 トークンとして 48,000 トークン — コンテキストの約 24% が一瞬で消えます。

動画コンテキスト消費の試算:
  30 秒の動画 × 1 fps = 30 フレーム
  30 フレーム × 1,600 トークン = 48,000 トークン
  200,000 トークン中の 24% を消費

  1 分の動画 × 1 fps = 60 フレーム
  60 フレーム × 1,600 トークン = 96,000 トークン
  200,000 トークン中の 48% を消費

UI のスクリーンショットを数枚読ませるだけでも数千トークン、動画解析をしようとすればコンテキストの半分近くが溶けます。これが「画像を読むとコンテキストが溶ける」問題の本質です。

解決策 — ローカル VLM へのオフロード

アーキテクチャの考え方

この問題の解決策は明快です。画像・動画の解析をローカル VLM に委譲し、Claude Code にはテキストの解析結果だけを返すというアプローチです。

従来のアプローチ:
  画像 → [base64エンコード] → Claude Code のコンテキスト → 解析
  消費: 約 1,600 トークン / 枚

オフロードアプローチ:
  画像 → [ローカル VLM] → テキスト要約 → Claude Code のコンテキスト
  消費: 約 100〜300 トークン（テキストのみ）

「テキスト要約」は数百トークン程度で済むため、コンテキスト消費を 80〜95% 削減できます。

MCP サーバーによる連携

Claude Code は MCP（Model Context Protocol）を通じて外部ツールと連携できます。ローカル VLM を MCP サーバーとして公開することで、Claude Code は「画像を解析して」とツールを呼ぶだけで、裏側でローカル VLM が処理を行い、テキスト結果だけがコンテキストに載ります。

Claude Code ←→ MCP Protocol ←→ VLM MCP Server ←→ ローカル VLM
                                     ↓
                              画像/動画を直接処理
                                     ↓
                              テキスト要約を返却

この方式の利点は 3 つあります。

1. コンテキスト節約: 画像データがコンテキストに載らない
2. プライバシー: 画像がクラウドに送信されない
3. コスト削減: Claude API の入力トークン課金を回避

Qwen3-VL — ローカル VLM の有力候補

モデルの特徴

Alibaba Cloud の Qwen チームが開発した Qwen3-VL は、現時点で最も強力なオープンソース VLM の一つです。

8B モデルは M1/M2/M3/M4 Mac の統合メモリでも動作し、個人開発者にとって現実的な選択肢です。

対応機能

• 画像理解: 写真、図表、スクリーンショットの解析
• 動画理解: ネイティブ 256K コンテキスト（1M まで拡張可能）、数時間の動画処理
• OCR: 32 言語対応、低光量・ブレ・傾きにも対応
• 空間認識: オブジェクト位置判定、2D/3D グラウンディング
• コード生成: 画像から HTML/CSS/JavaScript を生成

Ollama での起動

1
2
3

# Qwen3-VL-8B のダウンロードと起動
ollama pull qwen3-vl:8b
ollama run qwen3-vl:8b

実装パターン — Vision MCP サーバーの構築

パターン 1: 既存の Vision MCP サーバーを活用

複数の Vision MCP サーバーが既に公開されています。

パターン 2: vllm-mlx で Apple Silicon ネイティブ環境を構築

Mac ユーザーには vllm-mlx が強力な選択肢です。Apple Silicon の Metal GPU を活用し、Qwen3-VL をネイティブに実行できます。

1
2
3
4
5

# インストール
pip install vllm-mlx

# Qwen3-VL を起動（OpenAI/Anthropic 互換 API）
vllm-mlx serve --model Qwen/Qwen3-VL-8B-Instruct

vllm-mlx の特徴:

• OpenAI API 互換: /v1/chat/completions エンドポイント
• Anthropic Messages API 互換: /v1/messages エンドポイント
• MCP ツール呼び出し対応: Model Context Protocol ネイティブサポート
• マルチモーダル: テキスト・画像・動画・音声を統合処理
• 高速推論: M4 Max で Qwen3-0.6B が 402 tok/s

パターン 3: 自作 MCP サーバー

特定のユースケースに最適化するため、MCP サーバーを自作する方法もあります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# 概念的な MCP サーバーの構造
import subprocess
import json

def analyze_image(image_path: str, prompt: str = "この画像を説明してください") -> str:
    """ローカル VLM で画像を解析し、テキスト要約を返す"""
    result = subprocess.run(
        ["ollama", "run", "qwen3-vl:8b", prompt],
        input=open(image_path, "rb").read(),
        capture_output=True
    )
    return result.stdout.decode()

def analyze_video(video_path: str, fps: int = 1) -> str:
    """動画をフレーム分割し、各フレームを VLM で解析"""
    # ffmpeg でフレーム抽出
    subprocess.run([
        "ffmpeg", "-i", video_path,
        "-vf", f"fps={fps}",
        "/tmp/frames/frame_%04d.jpg"
    ])

    # 各フレームを解析
    descriptions = []
    for frame in sorted(glob("/tmp/frames/*.jpg")):
        desc = analyze_image(frame, "このフレームの内容を簡潔に説明してください")
        descriptions.append(desc)

    return "\n".join(descriptions)

このサーバーを MCP として公開すれば、Claude Code から analyze_image や analyze_video をツールとして呼び出せます。

コンテキスト効率の比較

VLM からのテキスト要約を 200 トークン程度に抑えれば、同じ 30 秒の動画解析が 48,000 トークン → 6,000 トークンに圧縮されます。

ハーネスエンジニアリングの視点

この「VLM オフロード」パターンは、ハーネスエンジニアリングの典型的な適用例です。

ハーネスエンジニアリングとは、AI エージェントの性能を最大化するために周辺環境（ハーネス）を設計するアプローチです。コンテキストウィンドウは希少資源であり、その使い方を最適化することがエージェントの能力に直結します。

ハーネス設計の原則 → VLM オフロードへの適用:

  コンテキストは希少資源
  → 画像データを直接載せない

  段階的に必要な情報だけをロード
  → VLM が要約したテキストだけを渡す

  専門処理は専門ツールに委譲
  → ビジョン処理はビジョン専門モデルに任せる

Claude は言語処理に特化した LLM です。画像の画素データを直接処理させるよりも、ビジョン専門のモデルが解析したテキスト要約を渡す方が、Claude の能力を最大限に引き出せます。

注意点と限界

VLM の解析精度

ローカル VLM（特に 8B 以下の小型モデル）は、Claude のビジョン機能と比較して精度が劣る場合があります。

精度が必要な場面では Claude のビジョンを直接使い、概要把握やバッチ処理にはローカル VLM を使う、という使い分けが現実的です。

ハードウェア要件

Apple Silicon Mac は統合メモリアーキテクチャのため、8B モデルを無理なく動かせます。

テキスト要約の情報損失

画像をテキストに要約する時点で、必ず情報の損失が発生します。以下のような場合は直接画像を送る方が適切です。

• ピクセル単位の精密な位置判定が必要な場合
• 画像内の微細なテキスト（小さいフォント）の読み取り
• 画像の色彩やグラデーションの正確な判定

まとめ

• 画像 1 枚で約 1,600 トークン消費: Claude Code で画像を直接扱うと、コンテキストウィンドウが急速に圧迫される
• ローカル VLM へのオフロードで 87% 削減: 画像処理をローカル VLM に委譲し、テキスト要約だけを Claude Code に返すことで、コンテキスト消費を大幅に抑えられる
• Qwen3-VL-8B が現実的な選択肢: Apple Silicon Mac の 8GB メモリで動作し、動画理解・OCR・空間認識に対応する
• MCP サーバーで透過的に連携: Claude Code の MCP 機能を使えば、ローカル VLM をツールとして自然に呼び出せる
• vllm-mlx で Apple Silicon ネイティブ実行: Metal GPU 加速により 400 tok/s 以上の推論速度を実現
• 精度とコンテキストのトレードオフ: 概要把握にはローカル VLM、精密解析には Claude ビジョンという使い分けが現実的
• ハーネスエンジニアリングの実践例: コンテキストを希少資源と捉え、専門処理を専門モデルに委譲するアプローチ

参考

• @ShadeLurk 氏のポスト（X Article）
• Anthropic: ビジョン — Claude API Docs
• Qwen3-VL — GitHub
• Qwen3-VL Technical Report (arXiv:2511.21631)
• vllm-mlx — Apple Silicon LLM Server
• Ollama: qwen3-vl
• Claude Code: MCP を使用してツールに接続する
• Z.AI Vision MCP Server
• gihyo.jp: Claude Code のコンテキストウィンドウを完全に理解する