VLM-MCP

English | 中文

MCP-сервер для понимания изображений на основе VLM. Поддерживает локальный llama.cpp и онлайн-VLM (например, Qwen3-VL-Flash) через единый OpenAI-совместимый API.

English

Возможности

• Два бэкенда: локальный llama.cpp + онлайн Qwen3-VL-Flash, единый OpenAI-совместимый API

• Трёхуровневый кэш: L1 — кэш кодирования изображений, L2 — кэш ответов (с TTL), L3 — KV-кэш llama-server

• Управление сессиями: контекст многоходовых диалогов, автоматическое вытеснение и очистка по таймауту

• Шаблоны промптов: встроенные 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)

Быстрый старт

Требования

Примечание: этот проект использует нативный бинарник llama.cpp (llama-server), а НЕ llama-cpp-python. Python-привязки не нужны — просто скачайте исполняемый файл llama.cpp.

Рекомендуемая модель: скачайте два файла из Qwen3-VL-8B-Instruct-GGUF:

8 ГБ видеопамяти достаточно. В режиме только онлайн (только бэкенд 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 endpoint: 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-инструменты

Шаблоны

Примеры

// 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:

Разработка

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

Часто задаваемые вопросы

llama-server работает на CPU?
Проверьте llama.ngl в config.json — 99 = всё на GPU, 0 = только CPU.

llama-server не запускается?
Убедитесь, что server_exe исполняемый и пути model/mmproj существуют. Проверьте llama_server.log.

Онлайн-бэкенд возвращает 401?
Недействительный API-ключ автоматически отключает бэкенд. Установите корректный ключ и перезапустите. Или установите "enabled": false, чтобы пропустить.

Конфликт портов?
MCP порт 11432, порт llama-server 11433. Измените llama.port в config.json или порт в server.py.

Related MCP server: MCP Vision Server

中文

特性

• 双后端支持：本地 llama.cpp + 在线 Qwen3-VL-Flash，统一 OpenAI 兼容 API

• 三层缓存：L1 图片编码缓存、L2 响应缓存（带 TTL）、L3 llama-server KV Cache

• 会话管理：多轮对话上下文保持，自动淘汰与超时清理

• 提示词模板：内置 describe / ocr / chart / translate / qa 模板

• 生命周期管理：llama-server 子进程与 MCP 同起同停，启动即用，无需手动管理

• 后端健康：API Key 错误自动禁用后端，支持手动启用/禁用

• 多图片来源：本地路径、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)

快速开始

环境要求

注意：本项目使用 llama.cpp 原生二进制（llama-server），不是 llama-cpp-python。 无需安装 Python 绑定（即无需llama-cpp-python，这个和单llama.cpp相互独立），只需下载 llama.cpp 可执行文件即可。

推荐模型下载：从 Qwen3-VL-8B-Instruct-GGUF 下载两个文件：

这样8G显存就可以跑

纯在线模式（仅用 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 表示全部 offload 到 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 工具

模板

使用示例

// 单次分析
{
  "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，可在代码中直接修改：

开发

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 Key 无效时会自动禁用该后端，设好 Key 后重启即可恢复。也可手动设 "enabled": false 跳过。

端口被占用？
MCP 端口 11432，llama-server 端口 11433。修改 config.json 中 llama.port 或 server.py 中端口号。

许可

MIT