de en es ja ko ru zh

vision-mcp

Name: vision-mcp
Author: skyone123

by skyone123

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

🖼️ vision-mcp

Servidor MCP de reconocimiento de imágenes VLM multimodal autohospedado

Pega imágenes en la terminal TUI → el cliente de IA las reconoce y devuelve automáticamente · los datos no salen de la red interna

MCP TypeScript Node Tests Build License: MIT Transport

Claude Code · Codex · OpenCode · cualquier cliente compatible con MCP

✨ Por qué usarlo

	Ventaja	Descripción
🔒	Despliegue privado, los datos no salen de la red	Conexión directa a tu VLM autohospedado, las imágenes no pasan por nubes de terceros
🔌	Compatible con OpenAI, backend intercambiable	vLLM / Ollama / GLM-4V / Qwen-VL a elegir, solo cambia la base URL, sin tocar código
🖼️	Pegar imagen en TUI y listo	Pega una imagen en la terminal, el cliente llama automáticamente a la herramienta para reconocerla, experiencia alineada con el MCP de reconocimiento de imágenes de Zhipu
🧩	Cuatro herramientas dedicadas	Comprensión general / OCR / comprensión de diagramas / conversión de UI a código, cada una con system prompt predefinido y salida estructurada
📥	Tres formas de entrada de imagen	Ruta local · URL http(s) · URI `data:`, el cliente envía lo que sea y se recibe lo que sea
🛡️	Los errores no se filtran	Los mensajes de error solo contienen texto estático/códigos de estado, nunca se filtra el cuerpo de respuesta del VLM ni el stack al cliente
⚡	Proceso único ligero	stdio, el cliente levanta el subproceso bajo demanda, sin proceso residente, sin estado en el servidor
🔁	Resiliencia integrada	Reintento automático una vez en 5xx/timeout, sin reintento en 4xx, timeout de petición, límite de tamaño de imagen
✅	Cobertura TDD completa	35 pruebas + ida y vuelta de extremo a extremo (VLM falso + InMemoryTransport)

Related MCP server: openai-vision-mcp-server

📐 Arquitectura

flowchart LR
    A["🖥️ TUI 客户端<br/>(Claude Code / Codex / OpenCode)"] -- stdio JSON-RPC --> B
    subgraph B["vision-mcp (Node, stdio)"]
        direction TB
        C["tools ×4<br/>analyze_image / extract_text /<br/>understand_diagram / ui_to_code"]
        C --> D["analyze()<br/>共享核心"]
        D --> E["imageSource<br/>路径/URL/data-URI → 归一化"]
        D --> F["vlmClient<br/>OpenAI 兼容 + 重试"]
    end
    F -- HTTPS chat/completions --> G["🧠 自托管 VLM<br/>(qwen-vl / glm-4v / ...)"]
    G -- JSON --> B
    B -- tool result --> A

🛠️ Herramientas

Todas comparten image_source (ruta local | URL http(s) | URI data:).

Herramienta	Parámetros específicos	Salida
`analyze_image`	`prompt` (obligatorio)	Descripción en lenguaje natural / preguntas y respuestas
`extract_text`	`prompt?`、`programming_language?`	Texto OCR (capturas de código con anotación de lenguaje)
`understand_diagram`	`diagram_type?` (omitido o `auto`)、`prompt?`	Descripción estructurada + réplica en mermaid/markdown
`ui_to_code`	`output_type` (`code`/`spec`/`description`)、`framework?` (`html`/`react-tailwind`)、`prompt?`	code/spec/description correspondiente

🚀 Inicio rápido

Clonar y compilar

git clone https://github.com/skyone123/vision-mcp.git
cd vision-mcp
npm install
npm run build      # 产出 dist/index.js + dist/index.d.ts
npm test           # 可选：35/35 测试

El cliente solo usa dist/index.js, anota su ruta absoluta (en adelante $DIST), la necesitarás en la configuración.

Ejemplo: Linux/macOS /home/you/vision-mcp/dist/index.js; Windows D:/git/vision-mcp/dist/index.js.

Variables de entorno

Variable	Valor por defecto	Obligatoria	Descripción
`VLM_BASE_URL`	—	✅	Base compatible con OpenAI, p. ej. `http://localhost:8000/v1` (con `/v1`)
`VLM_MODEL`	`qwen-vl-max`	—	Nombre del modelo
`VLM_API_KEY`	`""`	—	Token Bearer; solo si el backend requiere autenticación, si se deja vacío no se envía la cabecera `Authorization`
`VLM_TIMEOUT_MS`	`60000`	—	Timeout por petición
`VLM_MAX_IMAGE_BYTES`	`10485760`	—	Límite de imagen 10MB
`VLM_MAX_TOKENS`	`2048`	—	Límite de tokens de salida

Si falta VLM_BASE_URL, el arranque falla con error y sale, no falla en silencio.

🔧 Configuración

Paso 1 · Comprobar si el backend necesita API key

curl http://localhost:8000/v1/models

200 + lista de modelos → no necesita key
401/403 → sí necesita key, reintenta con la key: curl http://localhost:8000/v1/models -H "Authorization: Bearer tu-token"

Elige el modelo de visión de la respuesta:

curl -s http://localhost:8000/v1/models | grep '"id"'

Prueba que la capacidad de visión realmente procesa imágenes (lo más importante):

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的token" \
  -d '{
    "model": "qwen-vl-max",
    "messages": [{"role":"user","content":[
      {"type":"text","text":"一句话描述这张图"},
      {"type":"image_url","image_url":{"url":"https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/640px-PNG_transparency_demonstration_1.png"}}
    ]}]
  }'

Si devuelve texto normal → el endpoint funciona, copia esos valores al env.

Paso 2 · Escribirlo en el cliente

Sustituye $DIST por la ruta absoluta de dist/index.js anotada en el paso anterior, command usa node.

claude mcp add vision-mcp --scope user \
  --env VLM_BASE_URL=http://localhost:8000/v1 \
  --env VLM_MODEL=qwen-vl-max \
  -- node "$DIST"

Si necesita key, añade una línea más --env VLM_API_KEY=tu-token.

{
  "command": "node",
  "args": ["/absolute/path/to/vision-mcp/dist/index.js"],
  "env": {
    "VLM_BASE_URL": "http://localhost:8000/v1",
    "VLM_MODEL": "qwen-vl-max"
  }
}

Con key, añade "VLM_API_KEY": "tu-token" en env.

{
  "mcpServers": {
    "vision-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/vision-mcp/dist/index.js"],
      "env": { "VLM_BASE_URL": "http://localhost:8000/v1", "VLM_MODEL": "qwen-vl-max" }
    }
  }
}

[mcp_servers.vision-mcp]
command = "node"
args = ["/absolute/path/to/vision-mcp/dist/index.js"]
env = { VLM_BASE_URL = "http://localhost:8000/v1", VLM_MODEL = "qwen-vl-max" }

{
  "mcp": {
    "vision-mcp": {
      "type": "local",
      "command": ["node", "/absolute/path/to/vision-mcp/dist/index.js"],
      "environment": {
        "VLM_BASE_URL": "http://localhost:8000/v1",
        "VLM_MODEL": "qwen-vl-max"
      }
    }
  }
}

Los nombres de campos pueden variar ligeramente entre versiones de OpenCode; si la herramienta no aparece, consulta su documentación oficial de MCP.

Paso 3 · Verificación

claude mcp list          # 应看到 vision-mcp，状态 connected

El servidor MCP no necesita estar residente manualmente — el cliente levanta el subproceso bajo demanda. Luego pega una imagen en la conversación y pregunta "¿qué hay en la imagen?", el cliente llamará automáticamente a analyze_image; o explícitamente:

Usa la herramienta analyze_image para ver esta imagen:

💻 Desarrollo

npm run dev              # tsx 直接跑源码（开发期）
npm run build            # tsup 打包 dist/index.js
npm test                 # vitest，35/35
npx tsc --noEmit         # 类型检查

Estructura del código fuente:

src/
  config.ts          # env → VlmConfig
  imageSource.ts     # loadImage: 路径/URL/data-URI 归一化
  vlmClient.ts       # complete: 调 OpenAI 兼容端点 + 重试/超时
  analyze.ts         # 共享核心: loadImage + complete
  server.ts          # McpServer 注册 + stdio + main
  index.ts           # #!/usr/bin/env node 入口
  tools/
    analyzeImage.ts
    extractText.ts
    understandDiagram.ts
    uiToCode.ts

Cada archivo tiene una única responsabilidad y se puede probar de forma independiente; las cuatro herramientas son envoltorios finos de analyze(), cada una con su propio system prompt integrado.

🗺️ Hoja de ruta (extensiones opcionales)

Alcance actual: solo stdio · un solo backend · una sola imagen · sin persistencia. Extensiones bajo demanda:

Candidato	Valor	Sugerencia
Salida en streaming	La salida de `ui_to_code` puede ser muy larga, el streaming permite verla mientras se genera	👍 Merece la pena, mejora la UX
Preprocesamiento de imágenes	Redimensionar/comprimir por el lado largo antes de enviar, ahorra tokens y reduce timeouts	👍 Merece la pena, reduce costes
Salida estructurada	`extract_text`/`understand_diagram` devuelven JSON	🤔 Depende del caso
Transporte HTTP/SSE	Clientes múltiples compartidos, despliegue remoto	🤔 El stdio actual es suficiente, bajo demanda
Enrutamiento multi-backend	Enrutar distintas tareas a distintos VLM	❌ YAGNI
Procesamiento por lotes de vídeo/múltiples imágenes	—	❌ Fuera del alcance actual
Caché en servidor	Reconocimiento repetido de la misma imagen	❌ YAGNI

📄 Licencia

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Related MCP Connectors

Frenchie A
io.github.Lab94
OCR, transcription, file extraction, and image generation for AI agents via MCP.
AI & Machine Learning Image & Video Processing Speech Processing
72
https://mcp.getfrenchie.dev
OneOver B
com.oneover
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
AI & Machine Learning Image & Video Processing Audio Processing
181
https://api.oneover.com/functions/v1/mcp
Tastepix AOAuth
io.github.paablobello
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
AI & Machine Learning Image & Video Processing Multimedia Processing
101
https://mcp.tastepix.com/mcp
Tastepix AOAuth
com.tastepix.mcp
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models and 10 tools: up to 4 images per call, SVG vectorization, editing and more. Remote MCP with OAuth, no API keys. Pay per image, no subscription.
AI & Machine Learning Image & Video Processing
101
https://mcp.tastepix.com/mcp

Related MCP Servers

readpic MCP Server
Image & Video Processing AI & Machine Learning
tain-alphanume
F
license
Not graded
quality
D
maintenance
Enables AI clients like Claude to understand, analyze, and describe local images via VL models through the MCP protocol.
Updated 4 months ago (2026-07-10 07:17 UTC)
-
openai-vision-mcp-server
Image & Video Processing AI & Machine Learning
ygq-future
A
license
Not graded
quality
B
maintenance
Enables image analysis via OpenAI-compatible vision APIs, supporting local files, URLs, and base64 inputs with intelligent tiling for high-resolution images. Provides a secure, configurable MCP stdio server for structured vision analysis.
Updated 2 months ago (2026-08-25 08:59 UTC)
54 npm
3
MIT
Vision MCP
Image & Video Processing AI & Machine Learning
Amengclass
A
license
A
quality
B
maintenance
Enables any MCP client to perform image understanding and OCR via any OpenAI-compatible vision-language model. Supports local, private inference without images leaving the machine.
Updated 3 months ago (2026-08-10 07:07 UTC)
2
21 npm
MIT
ai-vision
Image & Video Processing AI & Machine Learning
kaijia323
A
license
A
quality
C
maintenance
Provides image recognition capabilities to MCP clients by integrating with OpenAI-compatible vision models, supporting local images, URLs, multi-image comparison, and model listing.
Updated 3 months ago (2026-08-10 15:34 UTC)
4
MIT