ollama-vision-mcp

English · 中文

Un servicio de puente mínimo que proporciona capacidades de visión local para VS Code Copilot utilizando modelos de solo texto (p. ej., DeepSeek).

Cuando Copilot utiliza un modelo de solo texto, no puede "ver" imágenes directamente. Este servidor MCP cubre esa carencia: colocas una captura de pantalla en una carpeta; Copilot lee la imagen a través de este puente → la envía a un modelo de visión local de Ollama → recibe una descripción de texto, que el modelo de solo texto puede entender.

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)

Herramientas

Related MCP server: Hybrid Vision MCP Server

Alcance de esta herramienta

Este paquete es solo una capa de puente. Se comunica con Ollama puramente mediante HTTP (compatible con OpenAI /v1/chat/completions y /v1/models).

No se encarga de:

• Instalar Ollama, iniciar ollama serve, descargar modelos o gestionar la configuración de los modelos;

• Acceder al portapapeles, mecanismos internos del IDE o cualquier servicio de red que no sea tu Ollama local.

Eres totalmente responsable de instalar Ollama y descargar los modelos (consulta Requisitos previos).

Requisitos previos

Debes configurar lo siguiente por tu cuenta:

• Python 3.10+

• Ollama instalado y en ejecución: ollama serve

• Al menos un modelo de visión descargado; recomendado:

  bash

  ollama pull qwen2.5vl:7b

  Otras opciones: qwen3-vl:8b, gemma3:12b, llama3.2-vision:11b, llava:7b. Elige un modelo adecuado para tu GPU; especifícalo más adelante mediante la variable de entorno VISION_MCP_MODEL.

🚀 Instalación rápida (recomendada)

Ejecuta un solo comando en la raíz del repositorio para completar la instalación y la configuración:

bash

cd ollama-vision-mcp
python setup_mcp.py

El script automáticamente:

1. Crear un entorno virtual dedicado (.venv) e instalar este paquete (sin contaminar el entorno global).

2. Detectar el servicio local de Ollama y listar los modelos de visión disponibles.

3. Guiarte de forma interactiva para establecer base_url, model, inbox, max_tokens, la compresión de imagen y una clave de API opcional.

4. Escribir la configuración en el .vscode/mcp.json del proyecto y/o en el archivo MCP global a nivel de usuario (%APPDATA%\Code\User\mcp.json), fusionándose con la configuración existente y sin sobrescribir tus otros servidores MCP.

Uso no interactivo (adecuado para CI/scripts):

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

Después de la instalación, recarga la ventana en VS Code (Ctrl+Shift+P → “Desarrollador: Recargar ventana”) para que la configuración surta efecto.

Si ya lo has ejecutado antes, también puedes reconfigurarlo simplemente con el comando ollama-vision-setup.

Verificar la instalación

En VS Code Copilot Chat (modo agente), introduce:

text

Run vision_status

Si el JSON devuelto contiene "ollama": { "ok": true, ... } y la lista de modelos, la conexión es correcta. Si ok es false, inicia primero Ollama (ollama serve) e inténtalo de nuevo.

Uso

1. Coloca capturas de pantalla en el directorio de inbox del proyecto (por defecto .ai/inbox). El servidor creará este directorio automáticamente cuando sea necesario.

2. Haz una pregunta en Copilot Chat, por ejemplo:

   “Mira las capturas de pantalla en el inbox y dime de qué trata este error.”

3. El agente llamará automáticamente a list_images → describe_image y responderá basándose en la descripción de texto.

Haz que el agente sea más inteligente (opcional): Copia el archivo de instrucciones ya preparado .github/instructions/ollama-vision/vision-tools.instructions.md en la misma ruta de tu proyecto. Enseña al agente el flujo de trabajo completo de visión — orden de llamada (list_images → describe_image → extract_text), selección de modo, resolución de problemas y cómo guiarte para colocar capturas de pantalla en el inbox. Como instrucción de archivo de VS Code, se descubre bajo demanda siempre que la tarea implique imágenes, por lo que funciona directamente sin configuración.

Referencia de variables de entorno

Alias de compatibilidad: VISION_MODEL, VISION_BASE_URL, VISION_INBOX, VISION_API_KEY.

Instalación manual (alternativa)

Si necesitas control manual completo sobre cada paso, consulta el proceso a continuación.

1. Crear un entorno e instalar

bash

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

Después de la instalación, tienes dos comandos:

• ollama-vision-mcp — inicia el servidor MCP

• ollama-vision-setup — acceso directo de configuración interactiva

2. Registrar con VS Code

Copia lo siguiente en el .vscode/mcp.json de tu proyecto (solo proyecto) o en el archivo a nivel de usuario %APPDATA%\Code\User\mcp.json (todos los proyectos). Asegúrate de cambiar command a la ruta absoluta del intérprete de Python de tu entorno virtual:

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 debe ser la ruta absoluta al intérprete de Python dentro del entorno virtual. También puedes ejecutar ollama-vision-setup --project para generar este archivo automáticamente. El servidor utiliza os.getcwd() cuando se invoca, por lo que las rutas relativas (como path y el directorio de inbox) se resolverán en relación con la raíz del proyecto donde se inicia el servidor.

Prueba de humo

Ejecuta el siguiente script para comprobar la conectividad con Ollama, listar el contenido del inbox y realizar una llamada de visión real a la primera imagen:

bash

python examples/smoke_test.py

Licencia

MIT