Skip to main content
Glama
deenesjakoruzh
skyone123

vision-mcp

by skyone123
OverviewSchemaRelated ServersScoreDiscussions
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: readpic 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

MIT © 2026 luyuxin

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd
A
license - permissive license
Not graded
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • Frenchie

    OCR, transcription, file extraction, and image generation for AI agents via MCP.

  • mcp

    Generate images with any major model — one API key, one prepaid balance, one MCP.

  • anythingmcp

    Self-hosted MCP gateway: turn any API, database or MCP server into AI connectors — no code.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/skyone123/vision-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server