Skip to main content
Glama
deenesjakoruzh
YC-CLT

vlm-mcp

by YC-CLT
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

VLM-MCP

GitHub License: MIT Python 3.11+ MCP

English | 中文

VLMベースの画像理解MCPサーバー。統一されたOpenAI互換APIを介して、ローカルのllama.cppとオンラインVLM（例：Qwen3-VL-Flash）をサポートします。

English

特徴

  • デュアルバックエンド：ローカルllama.cpp + オンラインQwen3-VL-Flash、統一OpenAI互換API

  • 3層キャッシュ：L1画像エンコードキャッシュ、L2レスポンスキャッシュ（TTL付き）、L3 llama-server KVキャッシュ

  • セッション管理：マルチターン会話コンテキスト、自動退避とタイムアウトクリーンアップ

  • プロンプトテンプレート：組み込みのdescribe / ocr / chart / translate / qa

  • ライフサイクル管理：llama-serverサブプロセスがMCPと連動して自動起動・停止、手動管理不要

  • バックエンドヘルス：APIキーエラー時にバックエンドを自動無効化、手動での有効化・無効化をサポート

  • マルチソース画像：ローカルパス、HTTP URL、Base64 Data URI、生のBase64フォールバック

アーキテクチャ

MCP Client (SSE :11432)
       │
       ▼
  server.py ── tool layer (analyze_image / create_session / ...)
       │
       ├── session_manager.py ── session lifecycle
       ├── cache.py ── L1 image cache + L2 response cache
       ├── image_utils.py ── image parsing (path/URL/Base64)
       │
       ▼
  providers/ ── OpenAI-compatible interface
       │
       ├── llama-cpp (localhost:11433) ← auto-launched by llama_launcher.py
       └── qwen-vl (dashscope API)

クイックスタート

環境要件

コンポーネント

備考

Python 3.11+

ランタイム

uv

パッケージマネージャー

llama.cpp

ネイティブバイナリ（llama-server）、CUDAビルドが必要

Qwen3-VL-8B GGUF

言語モデル + ビジョンプロジェクター

注意：このプロジェクトはllama.cppネイティブバイナリ（llama-server）を使用し、llama-cpp-pythonは使用しません。 Pythonバインディングは不要です。llama.cpp実行ファイルをダウンロードするだけです。

推奨モデル：Qwen3-VL-8B-Instruct-GGUFから2つのファイルをダウンロード：

ファイル

推奨

備考

ビジョンモデル

Qwen3VL-8B-Instruct-Q4_K_M.gguf

Q4_K_M量子化、速度と精度のバランス

ビジョンプロジェクター

mmproj-Qwen3VL-8B-Instruct-F16.gguf

F16である必要があります。量子化しないでください

8GBのVRAMで十分です。オンライン専用モード（qwen-vlバックエンドのみ）では、llama.cppとGGUFモデルをスキップできます。

インストール

git clone https://github.com/YC-CLT/VLM-mcp.git
cd VLM-mcp
uv sync

設定

cp config.example.json config.json

config.jsonを編集：

{
  "backends": {
    "llama-cpp": {
      "enabled": true,
      "base_url": "http://localhost:11433/v1",
      "api_key": "sk-no-key-required",
      "model_name": "qwen3-vl"
    },
    "qwen-vl": {
      "enabled": false,
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "your-dashscope-api-key",
      "model_name": "qwen-vl-flash"
    }
  },
  "default_backend": "llama-cpp",
  "cache_enabled": true,
  "llama": {
    "server_exe": "llama-server",
    "model": "D:/path/to/Qwen3VL-8B-Instruct-Q4_K_M.gguf",
    "mmproj": "D:/path/to/mmproj-Qwen3VL-8B-Instruct-F16.gguf",
    "ngl": 99
  }
}

主要フィールド：

  • backends.<name>.enabled：falseに設定するとバックエンドを手動で無効化

  • llama.model / llama.mmproj：モデルファイルの絶対パス（必須）

  • llama.ngl：GPUレイヤー数、99 = 全GPU、0 = CPUのみ

  • llama.server_exe：llama-server実行ファイル、デフォルトはPATHから検索

実行

uv run main.py

llama-serverサブプロセスはMCPと連動して自動起動・停止します。手動管理は不要です。

MCP SSEエンドポイント：http://127.0.0.1:11432/sse

任意のディレクトリから実行：uv run --directory D:\CodeFile\VLM-mcp main.py

MCPクライアント設定

MCPクライアント設定に追加：

{
  "mcpServers": {
    "vlm-mcp": {
      "url": "http://127.0.0.1:11432/sse"
    }
  }
}

MCPツール

ツール

パラメータ

説明

analyze_image

image, prompt, template, params, backend, session_id

テンプレートとセッションをサポートした画像分析

create_session

backend

マルチターン会話セッションを作成

close_session

session_id

セッションを閉じる

list_sessions

—

すべてのアクティブなセッションを一覧表示

list_backends

—

バックエンドとそのステータスを一覧表示

list_templates

—

利用可能なプロンプトテンプレートを一覧表示

テンプレート

テンプレート

パラメータ

説明

describe

—

一般的な画像説明

ocr

—

テキスト抽出

chart

—

チャート分析

translate

target_lang

画像翻訳（デフォルト：zh）

qa

question

画像Q&A

使用例

// Single analysis
{
  "tool": "analyze_image",
  "args": {
    "image": "D:/photos/cat.png",
    "prompt": "What is in this image?"
  }
}

// Using template
{
  "tool": "analyze_image",
  "args": {
    "image": "https://example.com/chart.png",
    "template": "chart"
  }
}

// Multi-turn session
{ "tool": "create_session", "args": { "backend": "llama-cpp" } }
// → { "session_id": "xxx" }
{ "tool": "analyze_image", "args": { "image": "...", "prompt": "...", "session_id": "xxx" } }
{ "tool": "analyze_image", "args": { "prompt": "Tell me more", "session_id": "xxx" } }
{ "tool": "close_session", "args": { "session_id": "xxx" } }

設定定数

config.py内の非機密定数：

定数

デフォルト

説明

IMAGE_MAX_SIZE_MB

20

画像の最大サイズ

IMAGE_DOWNLOAD_TIMEOUT

10

画像ダウンロードタイムアウト（秒）

CACHE_IMAGE_MAX_ENTRIES

100

L1キャッシュ上限

CACHE_RESPONSE_MAX_ENTRIES

500

L2キャッシュ上限

CACHE_RESPONSE_TTL_ONLINE

3600

オンラインバックエンドキャッシュTTL（秒）

CACHE_RESPONSE_TTL_LOCAL

1800

ローカルバックエンドキャッシュTTL（秒）

SESSION_TTL

1800

セッションタイムアウト（秒）

SESSION_MAX

5

バックエンドあたりの最大セッション数

LOG_LEVEL

"INFO"

ログレベル

開発

uv sync --dev
uv run pytest tests/ -v

よくある質問

llama-serverがCPUで動作していますか？
config.jsonのllama.nglを確認してください。99 = 全GPU、0 = CPUのみ。

llama-serverが起動に失敗しますか？
server_exeが実行可能であることと、model/mmprojのパスが存在することを確認してください。llama_server.logを確認してください。

オンラインバックエンドが401を返しますか？
無効なAPIキーはバックエンドを自動無効化します。有効なキーを設定して再起動してください。または"enabled": falseに設定してスキップしてください。

ポート競合？
MCPポート11432、llama-serverポート11433。config.jsonのllama.portまたはserver.pyのポートを変更してください。

Related MCP server: MCP Vision Server

中文

特徴

  • デュアルバックエンドサポート：ローカルllama.cpp + オンラインQwen3-VL-Flash、統一OpenAI互換API

  • 3層キャッシュ：L1画像エンコードキャッシュ、L2レスポンスキャッシュ（TTL付き）、L3 llama-server KVキャッシュ

  • セッション管理：マルチターン会話コンテキスト保持、自動退避とタイムアウトクリーンアップ

  • プロンプトテンプレート：組み込みのdescribe / ocr / chart / translate / qaテンプレート

  • ライフサイクル管理：llama-serverサブプロセスがMCPと同時に起動・停止、起動後すぐに使用可能、手動管理不要

  • バックエンドヘルス：APIキーエラー時にバックエンドを自動無効化、手動での有効化・無効化をサポート

  • マルチソース画像：ローカルパス、HTTP URL、Base64 Data URI、純粋なBase64フォールバック

アーキテクチャ

MCP Client (SSE :11432)
       │
       ▼
  server.py ── 工具层 (analyze_image / create_session / ...)
       │
       ├── session_manager.py ── 会话生命周期
       ├── cache.py ── L1 图片缓存 + L2 响应缓存
       ├── image_utils.py ── 图片解析 (路径/URL/Base64)
       │
       ▼
  providers/ ── OpenAI 兼容接口
       │
       ├── llama-cpp (localhost:11433) ← llama_launcher.py 自动启动
       └── qwen-vl (dashscope API)

クイックスタート

環境要件

コンポーネント

説明

Python 3.11+

ランタイム環境

uv

パッケージ管理

llama.cpp

ネイティブバイナリ（llama-server）、CUDA版が必要

Qwen3-VL-8B GGUF

言語モデル + ビジョンプロジェクター

注意：このプロジェクトはllama.cppネイティブバイナリ（llama-server）を使用し、llama-cpp-pythonではありません。 Pythonバインディングのインストールは不要です（llama-cpp-pythonは不要で、これは単体のllama.cppとは独立しています）。llama.cpp実行ファイルをダウンロードするだけでOKです。

推奨モデルのダウンロード：Qwen3-VL-8B-Instruct-GGUFから2つのファイルをダウンロード：

ファイル

推奨

説明

ビジョンモデル

Qwen3VL-8B-Instruct-Q4_K_M.gguf

Q4_K_M量子化、速度と精度のバランス

画像エンコーダー

mmproj-Qwen3VL-8B-Instruct-F16.gguf

F16を推奨、量子化不要

これで8GBのVRAMで動作します

純オンラインモード（qwen-vlバックエンドのみ）では、llama.cppとGGUFモデルをスキップできます。

インストール

git clone https://github.com/YC-CLT/VLM-mcp.git
cd VLM-mcp
uv sync

設定

cp config.example.json config.json

config.jsonを編集：

{
  "backends": {
    "llama-cpp": {
      "enabled": true,
      "base_url": "http://localhost:11433/v1",
      "api_key": "sk-no-key-required",
      "model_name": "qwen3-vl"
    },
    "qwen-vl": {
      "enabled": false,
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "your-dashscope-api-key",
      "model_name": "qwen-vl-flash"
    }
  },
  "default_backend": "llama-cpp",
  "cache_enabled": true,
  "llama": {
    "server_exe": "llama-server",
    "model": "D:/path/to/Qwen3VL-8B-Instruct-Q4_K_M.gguf",
    "mmproj": "D:/path/to/mmproj-Qwen3VL-8B-Instruct-F16.gguf",
    "ngl": 99
  }
}

主要フィールド：

  • backends.<name>.enabled：falseに設定するとバックエンドを手動で無効化

  • llama.model / llama.mmproj：ローカルモデルファイルの絶対パス（必須）

  • llama.ngl：GPUレイヤー数、99はすべてGPUにオフロード、0は純CPU

  • llama.server_exe：llama-server実行ファイル、デフォルトはPATHから検索

実行

uv run main.py

起動後、llama-serverサブプロセスが自動的に起動し、MCP終了時に自動停止します。llama-serverの手動管理は不要です。

MCP SSEエンドポイント：http://127.0.0.1:11432/sse

任意のディレクトリから実行：uv run --directory D:\CodeFile\VLM-mcp main.py

MCPクライアント設定

MCPクライアント設定ファイルに追加：

{
  "mcpServers": {
    "vlm-mcp": {
      "url": "http://127.0.0.1:11432/sse"
    }
  }
}

MCPツール

ツール

パラメータ

説明

analyze_image

image, prompt, template, params, backend, session_id

画像分析、テンプレートとセッションをサポート

create_session

backend

マルチターン会話セッションを作成

close_session

session_id

セッションを閉じる

list_sessions

—

すべてのアクティブなセッションを一覧表示

list_backends

—

バックエンドとそのステータスを一覧表示

list_templates

—

利用可能なプロンプトテンプレートを一覧表示

テンプレート

テンプレート

パラメータ

説明

describe

—

一般的な画像説明

ocr

—

テキスト抽出

chart

—

チャート分析

translate

target_lang

画像翻訳（デフォルト：中国語）

qa

question

画像Q&A

使用例

// 单次分析
{
  "tool": "analyze_image",
  "args": {
    "image": "D:/photos/cat.png",
    "prompt": "这张图片里有什么？"
  }
}

// 使用模板
{
  "tool": "analyze_image",
  "args": {
    "image": "https://example.com/chart.png",
    "template": "chart"
  }
}

// 多轮会话
{ "tool": "create_session", "args": { "backend": "llama-cpp" } }
// → { "session_id": "xxx" }
{ "tool": "analyze_image", "args": { "image": "...", "prompt": "...", "session_id": "xxx" } }
{ "tool": "analyze_image", "args": { "prompt": "继续分析", "session_id": "xxx" } }
{ "tool": "close_session", "args": { "session_id": "xxx" } }

設定定数

非機密定数はconfig.pyに集約されており、コード内で直接変更できます：

定数

デフォルト

説明

IMAGE_MAX_SIZE_MB

20

画像の最大サイズ

IMAGE_DOWNLOAD_TIMEOUT

10

画像ダウンロードタイムアウト（秒）

CACHE_IMAGE_MAX_ENTRIES

100

L1キャッシュ上限

CACHE_RESPONSE_MAX_ENTRIES

500

L2キャッシュ上限

CACHE_RESPONSE_TTL_ONLINE

3600

オンラインバックエンドキャッシュTTL（秒）

CACHE_RESPONSE_TTL_LOCAL

1800

ローカルバックエンドキャッシュTTL（秒）

SESSION_TTL

1800

セッションタイムアウト（秒）

SESSION_MAX

5

バックエンドあたりの最大セッション数

LOG_LEVEL

"INFO"

ログレベル

開発

uv sync --dev
uv run pytest tests/ -v

よくある質問

llama-serverがCPUで動作していますか？
config.jsonのllama.nglが99（全GPU）かどうか確認してください。0は純CPUです。

llama-serverの起動に失敗しましたか？
server_exeが実行可能（PATH内または絶対パス）であることと、model/mmprojのパスが存在することを確認してください。llama_server.logを確認してください。

オンラインバックエンドの401エラー？
APIキーが無効な場合、そのバックエンドは自動的に無効化されます。キーを設定して再起動すると復元できます。手動で"enabled": falseに設定してスキップすることもできます。

ポートが使用中？
MCPポート11432、llama-serverポート11433。config.jsonのllama.portまたはserver.pyのポート番号を変更してください。

ライセンス

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP Vision Server

    LZMW
    A
    license
    A
    quality
    D
    maintenance
    Provides advanced image analysis capabilities including object recognition, OCR text extraction, and multi-turn visual dialogues using OpenAI-compatible APIs. It supports both local files and Base64 inputs with additional features for session persistence and web-based configuration management.
    3
    MIT

  • vision-mcp

    knownothing20
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to analyze images using any OpenAI-compatible vision API, providing tools for image analysis, OCR, error diagnosis, diagram understanding, and chart analysis.
    MIT