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 | 中文

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