ollama-vision-mcp

English · 中文

VS Code Copilot가 텍스트 전용 모델(예: DeepSeek)을 사용할 때 로컬 비전 기능을 제공하는 최소한의 브리징 서비스입니다.

Copilot이 텍스트 전용 모델을 사용하면 이미지를 직접 "볼" 수 없습니다. 이 MCP 서버는 그 공백을 메웁니다. 폴더에 스크린샷을 넣으면 Copilot이 이 브리지를 통해 이미지를 읽고, 로컬 Ollama 비전 모델에 보내며, 텍스트 전용 모델이 이해할 수 있는 텍스트 설명을 받아옵니다.

VS Code Copilot Chat (Agent mode, text-only model)
        │  MCP stdio
        ▼
ollama-vision-mcp (this package)
        │  Read local image → base64 → POST /v1/chat/completions
        ▼
Ollama (local vision model, e.g., qwen2.5vl:7b)

도구

Related MCP server: Hybrid Vision MCP Server

이 도구의 범위

이 패키지는 단지 브리지 계층입니다. Ollama와 순수하게 HTTP(OpenAI 호환 /v1/chat/completions 및 /v1/models)로 통신합니다.

다음은 처리하지 않습니다:

• Ollama 설치, ollama serve 시작, 모델 가져오기, 모델 구성 관리;

• 클립보드 접근, IDE 내부 메커니즘, 로컬 Ollama 외의 네트워크 서비스 접근.

Ollama 설치 및 모델 가져오기는 전적으로 사용자 책임입니다(전제 조건 참조).

전제 조건

다음은 직접 설정해야 합니다:

• Python 3.10+

• Ollama가 설치되어 실행 중이어야 함: ollama serve

• 비전 모델을 하나 이상 가져와야 합니다. 권장 사항:

  bash

  ollama pull qwen2.5vl:7b

  기타 옵션: qwen3-vl:8b, gemma3:12b, llama3.2-vision:11b, llava:7b. GPU에 적합한 모델을 선택하고, 나중에 VISION_MCP_MODEL 환경 변수로 지정하세요.

🚀 빠른 설치 (권장)

저장소 루트에서 단일 명령을 실행하여 설치 및 구성을 완료하세요:

bash

cd ollama-vision-mcp
python setup_mcp.py

스크립트는 자동으로 다음을 수행합니다:

1. 전용 가상 환경(.venv)을 만들고 이 패키지를 설치합니다(전역 환경을 오염시키지 않음).

2. 로컬 Ollama 서비스를 감지하고 사용 가능한 비전 모델을 나열합니다.

3. base_url, model, inbox, max_tokens, 이미지 압축, 선택적 API 키를 대화형으로 안내합니다.

4. 구성을 프로젝트의 .vscode/mcp.json 및/또는 사용자 수준의 전역 MCP 파일(%APPDATA%\Code\User\mcp.json)에 기록합니다. 기존 설정과 병합하며 다른 MCP 서버를 덮어쓰지 않습니다.

비대화형 사용(CI/스크립트에 적합):

bash

python setup_mcp.py --yes --project --model qwen2.5vl:7b
python setup_mcp.py --print         # Only prints the config JSON, does not write to file

설치 후 VS Code에서 창 다시 로드(Ctrl+Shift+P → “Developer: Reload Window”)를 실행하여 구성을 적용하세요.

이전에 실행한 적이 있다면 ollama-vision-setup 명령만으로 다시 구성할 수도 있습니다.

설치 확인

VS Code Copilot Chat(에이전트 모드)에서 다음을 입력하세요:

text

Run vision_status

반환된 JSON에 "ollama": { "ok": true, ... } 및 모델 목록이 포함되어 있으면 연결이 성공한 것입니다. ok가 false이면 먼저 Ollama(ollama serve)를 시작한 후 다시 시도하세요.

사용 방법

1. 프로젝트의 받은 편지함 디렉터리(기본값 .ai/inbox)에 스크린샷을 넣으세요. 서버는 필요할 때 이 디렉터리를 자동으로 생성합니다.

2. Copilot Chat에서 예를 들어 다음과 같이 질문하세요:

   “받은 편지함의 스크린샷을 보고 이 오류가 무엇에 관한 것인지 알려주세요.”

3. 에이전트는 자동으로 list_images → describe_image를 호출하고 텍스트 설명을 기반으로 답변합니다.

에이전트를 더 똑똑하게 만들기(선택 사항): 준비된 지시 파일 .github/instructions/ollama-vision/vision-tools.instructions.md을 프로젝트의 동일한 경로에 복사하세요. 이 파일은 에이전트에게 전체 비전 워크플로우(호출 순서 list_images → describe_image → extract_text, 모드 선택, 문제 해결, 받은 편지함에 스크린샷을 넣도록 안내하는 방법)를 가르칩니다. VS Code 파일 지시사항으로서 이미지와 관련된 작업이 있을 때마다 필요 시 발견되므로 별도 설정 없이 바로 사용할 수 있습니다.

환경 변수 참조

호환 별칭: VISION_MODEL, VISION_BASE_URL, VISION_INBOX, VISION_API_KEY.

수동 설치 (대안)

각 단계를 완전히 수동으로 제어해야 하는 경우 아래 과정을 참조하세요.

1. 환경 생성 및 설치

bash

cd ollama-vision-mcp
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate    # macOS / Linux
pip install -e .

설치 후 두 가지 명령을 사용할 수 있습니다:

• ollama-vision-mcp — MCP 서버 시작

• ollama-vision-setup — 대화형 구성 단축키

2. VS Code 등록

프로젝트의 .vscode/mcp.json(프로젝트 전용) 또는 사용자 수준 파일 %APPDATA%\Code\User\mcp.json(모든 프로젝트)에 다음을 복사하세요. command를 가상 환경의 Python 인터프리터 절대 경로로 변경해야 합니다:

json

{
  "servers": {
    "ollama-vision": {
      "type": "stdio",
      "command": "D:/MyRepos/ollama-vision-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "ollama_vision_mcp"],
      "env": {
        "VISION_MCP_BASE_URL": "http://localhost:11434/v1",
        "VISION_MCP_MODEL": "qwen2.5vl:7b",
        "VISION_MCP_INBOX": ".ai/inbox"
      }
    }
  }
}

⚠️ command는 가상 환경 내부의 Python 인터프리터에 대한 절대 경로여야 합니다. ollama-vision-setup --project를 실행하여 이 파일을 자동으로 생성할 수도 있습니다. 서버는 호출될 때 os.getcwd()를 사용하므로 상대 경로(path 및 받은 편지함 디렉터리 등)는 서버가 시작된 프로젝트 루트를 기준으로 확인됩니다.

스모크 테스트

다음 스크립트를 실행하여 Ollama 연결을 확인하고 받은 편지함 내용을 나열한 후 첫 번째 이미지에 실제 비전 호출을 수행하세요:

bash

python examples/smoke_test.py

라이선스

MIT