Skip to main content
Glama
deenesjakoruzh
YC-CLT

vlm-mcp

by YC-CLT
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

VLM-MCP

GitHub License: MIT Python 3.11+ MCP

English | 中文

基于 VLM 的图像理解 MCP Server。通过统一的 OpenAI 兼容 API，支持本地 llama.cpp 和在线 VLM（如 Qwen3-VL-Flash）。

English

特性

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

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

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

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

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

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

  • 多图片来源：本地路径、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 下载两个文件：

文件

推荐

说明

视觉模型

Qwen3VL-8B-Instruct-Q4_K_M.gguf

Q4_K_M 量化，平衡速度与精度

视觉投影器

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

必须为 F16，请勿量化

8 GB 显存即可运行。纯在线模式（仅用 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

图片问答

使用示例

// 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 Key 无效会自动禁用该后端。设置有效 Key 后重启。或设 "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

  • 三层缓存：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)

快速开始

环境要求

组件

说明

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 可执行文件即可。

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

文件

推荐

说明

视觉模型

Qwen3VL-8B-Instruct-Q4_K_M.gguf

Q4_K_M 量化，平衡速度与精度

图像编码器

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

建议 F16，不必量化

这样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 工具

工具

参数

说明

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

图片问答

使用示例

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

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

许可

MIT

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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
    C
    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

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/YC-CLT/VLM-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server