Vision MCP

Permite que los LLM sin capacidad visual (como GLM) también puedan procesar imágenes en Claude Code / Codex.

Cómo funciona

Cuando el modelo principal encuentra una imagen, llama a la herramienta describe_image proporcionada por este MCP:

1. La herramienta lee el archivo de imagen local

2. Llama al modelo de visión que hayas configurado (Qwen-VL / GPT-4o / GLM-4V / Doubao o cualquier interfaz compatible con OpenAI)

3. Devuelve la descripción textual al modelo principal

4. El modelo principal continúa el razonamiento basándose en el texto

El modelo principal nunca toca el binario de la imagen, por lo que los modelos de solo texto también pueden usarlo.

El proyecto tiene cero dependencias de terceros (solo biblioteca estándar de Python), funciona con Python 3.8+ y no requiere instalación con pip.

Related MCP server: Image-Vision MCP Server

Instalación con un clic

git clone https://github.com/Ruiba0/Vision-MCP.git
cd vision-mcp
python3 install.py

En Windows no existe el comando python3, usa python install.py; lo mismo aplica para todos los python3 a continuación.

El script de instalación completará de forma interactiva:

• Te permite introducir la URL base / nombre del modelo / clave API del modelo de visión (con referencia de proveedores comunes)

• Registra el MCP en Claude Code (claude mcp add)

• Registra el MCP en Codex (escribe en ~/.codex/config.toml)

• Añade reglas de procesamiento de imágenes en ~/.claude/CLAUDE.md y ~/.codex/AGENTS.md

El script es idempotente y se puede ejecutar repetidamente.

Instalación manual

Si no quieres usar el script de instalación:

1. Configura el modelo de visión

   Copia config.example.json como config.json e introduce la configuración de tu modelo de visión:

   {
     "vision_api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
     "vision_model": "qwen-vl-max",
     "vision_api_key": "sk-你的key",
     "max_image_bytes": 10485760
   }

2. Regístrate en Claude Code

   claude mcp add --scope user vision -- python3 /绝对路径/server.py

   Añade --scope user para que esté disponible globalmente (si no lo añades, solo tendrá efecto en el directorio actual).

3. Regístrate en Codex

   Edita ~/.codex/config.toml y añade:

   [mcp_servers.vision]
   command = "python3"
   args = ["/绝对路径/server.py"]

4. Añade reglas de procesamiento de imágenes

   Añade el siguiente contenido en ~/.claude/CLAUDE.md y ~/.codex/AGENTS.md (para que el modelo principal llame activamente a la herramienta cuando encuentre imágenes):

   ## 图片处理
   
   当用户提到图片文件路径（.png/.jpg/.jpeg/.gif/.webp/.bmp），或要求查看/分析/识别某个图片文件时：
   
   - 先判断当前主模型自身是否具备视觉能力
   - 具备视觉（如 Claude Sonnet/Opus、GPT-4o、Qwen-VL 等多模态模型）→ 直接读取图片并分析
   - 不具备视觉（如 GLM 等纯文本模型）→ 调用 vision MCP 的 describe_image 工具，传入图片路径和问题
   - 不确定自身是否支持视觉时，默认调用 describe_image 工具作为兜底
   - 用户明确要求"用 MCP 看"或"调视觉模型"时，无论主模型是否支持视觉，都调用 describe_image 工具

Modelos de visión compatibles

Se puede usar cualquier modelo de visión compatible con el protocolo de OpenAI:

Si necesitas usar el protocolo nativo de Anthropic (como Claude), debes modificar vision_client.py por tu cuenta; actualmente solo se admite el protocolo compatible con OpenAI.

Cómo usar

Después de la instalación, reinicia Claude Code / Codex y en la conversación:

• "Ve a ~/Desktop/diagram.png y mira esta imagen"

• "Analiza el error en ~/Screenshots/error.jpg"

• "Reconoce todo el texto en ~/Documents/notes/page1.jpeg"

(En Windows, la ruta tiene la forma D:/temp/diagram.png, escríbela según tu sistema)

El modelo principal llamará automáticamente a la herramienta describe_image, que devuelve la descripción textual del modelo de visión, y el modelo principal continúa respondiendo basándose en la descripción.

Parámetros de la herramienta

describe_image(path: str, question: str = "详细描述这张图片的内容") -> str

• path: ruta absoluta del archivo de imagen, admite png/jpg/jpeg/gif/webp/bmp

• question: la pregunta que quieres hacer al modelo de visión, se puede ajustar según el escenario ("reconocer texto", "describir el diseño", "analizar gráficos", etc.)

Estructura del proyecto

vision-mcp/
├── server.py              # MCP 服务（内置 stdio JSON-RPC 实现，无 SDK 依赖）
├── vision_client.py       # 视觉模型调用（OpenAI 兼容协议，urllib 实现）
├── config.example.json    # 配置模板（提交到 git）
├── config.json            # 你的实际配置（gitignored）
├── install.py             # 一键安装脚本
└── README.md

Preguntas frecuentes

P: La llamada reporta 视觉模型连接失败 Comprueba si la ruta de vision_api_base es correcta. La herramienta añade /chat/completions después de la URL base, así que la URL base no debe llevar el sufijo /chat/completions.

P: La llamada reporta HTTP 401 La clave API no es válida o no tienes permiso para ese modelo. Comprueba si vision_api_key y vision_model coinciden con la plataforma correspondiente.

P: El modelo principal no llama a la herramienta automáticamente Confirma que las reglas de procesamiento de imágenes en CLAUDE.md / AGENTS.md se han añadido. Las palabras clave de las reglas (imagen, ver, analizar) guiarán al modelo principal para que llame a describe_image.

P: Quiero cambiar el modelo de visión Edita config.json y modifica los tres campos; no necesitas tocar el código. O vuelve a ejecutar python3 install.py para reconfigurar.

Dependencias

• Python 3.8+ (solo biblioteca estándar, no es necesario instalar ningún paquete con pip)

Licencia

MIT