de en es ja ko ru zh

vlm-mcp

Name: vlm-mcp
Author: YC-CLT

by YC-CLT

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

VLM-MCP

GitHub License: MIT Python 3.11+ MCP

English | 中文

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에서 두 파일을 다운로드하세요:

파일	권장	설명
비전 모델	`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 실행 파일만 다운로드하면 됩니다.

권장 모델 다운로드: Qwen3-VL-8B-Instruct-GGUF에서 두 파일을 다운로드하세요:

파일	권장	설명
비전 모델	`Qwen3VL-8B-Instruct-Q4_K_M.gguf`	Q4_K_M 양자화, 속도와 정밀도의 균형
이미지 인코더	`mmproj-Qwen3VL-8B-Instruct-F16.gguf`	F16 권장, 양자화할 필요 없음

이렇게 하면 8G 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

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

APICK AI A
app.apick
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
AI & Machine Learning Image & Video Processing
1511
SammaPix — Image & PDF tools for AI agents
io.github.samma1997
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
Image & Video Processing AI & Machine Learning
17
rostro AOAuth
dev.rostro
Turn any LLM multimodal; generate images, voices, videos, 3D models, music, and more.
Multimedia Processing Image & Video Processing Audio Processing
2
Frenchie A
io.github.Lab94
OCR, transcription, file extraction, and image generation for AI agents via MCP.
AI & Machine Learning Image & Video Processing Speech Processing
72

Related MCP Servers

Vision MCP
Image & Video Processing Multimedia Processing
i-richardwang
A
license
A
quality
D
maintenance
Enables image analysis and understanding using Vision Language Models through OpenAI-compatible APIs. Supports analyzing images from URLs or local files with custom prompts.
Updated 10 months ago (2025-12-26 05:40 UTC)
1
2
MIT
MCP Vision Server
Image & Video Processing Autonomous Agents Multimedia Processing
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.
Updated 8 months ago (2026-02-24 01:46 UTC)
3
MIT
api-vision-mcp
Image & Video Processing AI & Machine Learning
stzhiyang
F
license
Not graded
quality
D
maintenance
Enables image recognition using vision models via OpenAI-compatible APIs, supporting multiple platforms like OpenAI, DeepSeek, and Ollama.
Updated 3 months ago (2026-07-09 12:35 UTC)
-
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.
Updated 3 months ago (2026-07-25 06:58 UTC)
MIT

VLM-MCP

English

기능

아키텍처

빠른 시작

요구 사항

설치

구성

실행

MCP 클라이언트 설정

MCP 도구

템플릿

사용 예시

구성 상수

개발

자주 묻는 질문

中文

기능

아키텍처

빠른 시작

환경 요구 사항

설치

구성

실행

MCP 클라이언트 구성

MCP 도구

템플릿

사용 예시

구성 상수

개발

자주 묻는 질문

라이선스

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Vision MCP

MCP Vision Server

api-vision-mcp

vision-mcp