VLM-MCP

English | 中文

Servidor MCP de comprensión de imágenes basado en VLM. Soporta llama.cpp local y VLMs en línea (p. ej. Qwen3-VL-Flash) mediante una API unificada compatible con OpenAI.

English

Características

• Doble backend: llama.cpp local + Qwen3-VL-Flash en línea, API unificada compatible con OpenAI

• Caché de tres niveles: caché de codificación de imágenes L1, caché de respuestas L2 (con TTL), caché KV de llama-server L3

• Gestión de sesiones: contexto de conversación multi-turno, expulsión automática y limpieza por tiempo de espera

• Plantillas de prompt: describe / ocr / chart / translate / qa integradas

• Gestión del ciclo de vida: el subproceso llama-server se inicia/detiene automáticamente con MCP, sin gestión manual

• Salud del backend: desactivación automática de backends ante errores de clave API, soporte de activación/desactivación manual

• Imágenes de múltiples fuentes: ruta local, URL HTTP, URI de datos Base64, respaldo Base64 sin procesar

Arquitectura

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)

Inicio rápido

Requisitos

Nota: Este proyecto utiliza el binario nativo de llama.cpp (llama-server), NO llama-cpp-python. No se necesitan bindings de Python — solo descarga el ejecutable de llama.cpp.

Modelo recomendado: Descarga dos archivos de Qwen3-VL-8B-Instruct-GGUF:

8 GB de VRAM son suficientes. El modo solo en línea (solo backend qwen-vl) puede omitir llama.cpp y los modelos GGUF.

Instalación

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

Configuración

cp config.example.json config.json

Edita 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
  }
}

Campos clave:

• backends.<name>.enabled: establece false para desactivar manualmente un backend

• llama.model / llama.mmproj: rutas absolutas a los archivos del modelo (obligatorio)

• llama.ngl: capas de GPU, 99 = toda la GPU, 0 = solo CPU

• llama.server_exe: ejecutable de llama-server, por defecto busca en PATH

Ejecución

uv run main.py

El subproceso llama-server se inicia y detiene automáticamente con MCP. No se necesita gestión manual.

Endpoint SSE de MCP: http://127.0.0.1:11432/sse

Ejecuta desde cualquier directorio: uv run --directory D:\CodeFile\VLM-mcp main.py

Configuración del Cliente MCP

Añade a tu configuración de cliente MCP:

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

Herramientas MCP

Plantillas

Ejemplos

// 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" } }

Constantes de Configuración

Constantes no sensibles en config.py:

Desarrollo

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

Preguntas Frecuentes

¿llama-server ejecutándose en CPU?
Comprueba llama.ngl en config.json — 99 = toda la GPU, 0 = solo CPU.

¿llama-server no se inicia?
Verifica que server_exe sea ejecutable y que existan las rutas model/mmproj. Revisa llama_server.log.

¿El backend en línea devuelve 401?
Una clave API no válida desactiva automáticamente el backend. Establece una clave válida y reinicia. O establece "enabled": false para omitirlo.

¿Conflicto de puertos?
Puerto MCP 11432, puerto llama-server 11433. Cambia llama.port en config.json o el puerto en 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