vision-mcp

Servidor MCP ligero que aporta capacidades de visión a modelos de texto puro. Cuando el modelo principal encuentra imágenes (capturas de pantalla, capturas de UI, diagramas de flujo, capturas de error, etc.) pero no puede comprenderlas, a través de las herramientas MCP envía la imagen a un backend multimodal compatible con OpenAI (Qwen-VL, GPT-4o, Gemini, vLLM local, etc.) para su análisis y devuelve el resultado en texto.

主模型(纯文本) ──调用 MCP 工具──▶ vision-mcp ──Chat Completions──▶ 多模态模型
   Claude/Codex ◀──────文本结果───────◀──────────────────────────   Qwen-VL / GPT-4o / ...

Inicio rápido

Recomendado: inícialo directamente con bin/wrapper.sh incluido en el repositorio. En la primera invocación, el wrapper crea automáticamente un .venv en el directorio e instala las dependencias (prioriza uv; si no hay uv, usa venv+pip), sin necesidad de instalación manual; después ejecuta el server.py real. Válido para macOS / Linux.

# 方式一（推荐，免手动装依赖）：MCP client 指向 wrapper 即可
claude mcp add vision-mcp -- /绝对/路径/vision-mcp/bin/wrapper.sh

# 或先自测：wrapper 会自举依赖并启动 server
/绝对/路径/vision-mcp/bin/wrapper.sh --check

En Windows usa python -m venv + install.ps1, o directamente python server.py.

Related MCP server: vision-mcp

Instalación (compilación desde el código fuente)

Primero instala el servidor MCP en sí (Python):

# Windows
powershell -ExecutionPolicy Bypass -File .\install.ps1
# macOS / Linux
./install.sh

Luego conéctalo según tu cliente:

Claude Code

claude mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

Codex

codex mcp add vision-mcp -- \
  python /绝对/路径/vision-mcp/server.py

Tras modificar la configuración de MCP, reinicia el cliente para que surta efecto.

pi

cp pi-extensions/vision-mcp.ts ~/.pi/agent/extensions/
# 依赖：typebox（必需，工具参数模式定义）；sharp（可选，图片缩放，未装则自动降级为不缩放）
cd ~/.pi/agent/extensions && npm i sharp typebox

Tras copiarlo, reinicia pi o usa /reload para cargarlo automáticamente; no hace falta pi install. La extensión de pi admite control por capacidades: cuando el modelo principal admite imágenes de forma nativa (input incluye image), oculta automáticamente las tres herramientas de visión para evitar delegaciones innecesarias; solo se muestran en modelos de texto puro.

Configuración

Prioridad: config.json > variables de entorno del proceso > .env > valores predeterminados. config.json está en gitignore y no se incluye en el repositorio.

cp config.example.json config.json   # 再编辑 api_key 等字段

{
  "api": "openai-completions",
  "api_key": "sk-your-dashscope-api-key",
  "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
  "model": "qwen-vl-plus",
  "max_tokens": 4096,
  "timeout": 120,
  "max_retries": 2,
  "retry_backoff": 2
}

La extensión de pi lee además ~/.pi/vision-mcp/config.json (o especifícalo con VISION_CONFIG_PATH); las claves son las mismas que las anteriores.

Formatos admitidos: PNG / JPEG / WebP / GIF (BMP queda excluido porque los principales backends de visión no lo admiten).

Backends habituales: DashScope (predeterminado) VISION_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1; OpenAI model=gpt-4o; vLLM local base_url=http://localhost:8000/v1.

Comprobar la configuración

# wrapper 方式（依赖未装则先自举）
./bin/wrapper.sh --check
# 源码自建（依赖手动安装后）
python server.py --check   # 打印生效配置，API key 脱敏

Herramientas

• vision_analyze — comprensión general de imágenes. Parámetros: prompt (opcional), image/image_path/image_url/image_base64 (elegir uno de los cuatro).

• vision_ocr — extrae el texto de la imagen carácter por carácter. Parámetros iguales que analyze (sin prompt).

• vision_analyze_batch — análisis por lotes de varias imágenes. Parámetros: items (obligatorio; cada elemento es una fuente de imagen de entre las cuatro opciones, puede incluir prompt), prompt (opcional), concurrency (predeterminado 3, rango 1-8).

Código abierto

Se publica como código fuente abierto; son bienvenidos Fork / Issue / PR.