DeepSeek Vision MCP

Un servidor MCP v2 seguro y ligero que proporciona a cualquier agente compatible con MCP DeepSeek V4 Flash Vision: análisis de imágenes, descripciones fieles, OCR, comparaciones, localización de interfaz/objetos y cargas reutilizables mediante la API de archivos.

El servidor expone el modelo exacto deepseek-v4-flash-vision-exp sin incorporar cargas útiles de imágenes específicas del proveedor en cada integración de agente.

Herramientas

Referencias de imagen aceptadas:

• ruta local del lado del servidor

• URL pública http:// o https://

• data:image/...;base64,...

• ID de archivo file-api-... de DeepSeek

Related MCP server: vision-mcp

Por qué este servidor es delgado

El servidor MCP no ejecuta un modelo de visión local. Solo valida/normaliza las entradas de imagen y delega la inferencia a DeepSeek. Esto hace que el uso de CPU/RAM sea mínimo y permite que cualquier agente capaz de MCP obtenga visión sin incorporar formas de carga útiles específicas de DeepSeek en el propio agente.

Instalar con uv

git clone https://github.com/groxaxo/deepseek-vision-mcp.git
cd deepseek-vision-mcp

uv sync --locked

cp .env.example .env
# Set DEEPSEEK_API_KEY and allowed roots in .env

Para un host MCP local, stdio es el transporte preferido:

DEEPSEEK_API_KEY="..." \
DEEPSEEK_VISION_ALLOWED_ROOTS="/home/you/Pictures:/tmp/vision" \
uv run deepseek-vision-mcp

Para desarrollo con MCP Inspector:

DEEPSEEK_API_KEY="..." uv run mcp dev src/deepseek_vision_mcp/server.py

Configuración del host MCP

Configuración típica de stdio:

{
  "mcpServers": {
    "deepseek-vision": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/deepseek-vision-mcp",
        "run",
        "deepseek-vision-mcp"
      ],
      "env": {
        "DEEPSEEK_API_KEY": "YOUR_KEY",
        "DEEPSEEK_VISION_ALLOWED_ROOTS": "/home/you/Pictures:/tmp/vision"
      }
    }
  }
}

No comprometas la clave de API. Si el host puede heredar variables de entorno, prefiere inyectar DEEPSEEK_API_KEY desde tu gestor de secretos o shell.

Lanzador compartido seguro

run-mcp.py es útil cuando varios agentes locales comparten una instalación. Este:

• lee solo las variables de DeepSeek aprobadas del proceso o de un archivo de entorno;

• filtra secretos heredados no relacionados antes de lanzar el MCP;

• fuerza el transporte stdio;

• restringe las imágenes locales a raíces explícitas.

Por defecto lee ~/.hermes/.env y permite los directorios habituales de trabajo con imágenes bajo el directorio de inicio actual más /tmp. Anula esas opciones sin editar el script:

export DEEPSEEK_VISION_ENV_FILE="$HOME/.config/deepseek-vision.env"
export DEEPSEEK_VISION_ALLOWED_ROOTS="$HOME/Pictures:/tmp/vision"
./run-mcp.py

Configuración de Hermes:

mcp_servers:
  deepseek-vision:
    command: "/absolute/path/to/deepseek-vision-mcp/run-mcp.py"
    args: []
    enabled: true

Configuración de OpenCode:

{
  "mcp": {
    "deepseek-vision": {
      "type": "local",
      "command": ["/absolute/path/to/deepseek-vision-mcp/run-mcp.py"],
      "enabled": true
    }
  }
}

OMP y otros hosts MCP estándar pueden usar el ejemplo de mcpServers anterior con run-mcp.py como comando.

HTTP transmisible

export DEEPSEEK_API_KEY="..."
export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8000

uv run deepseek-vision-mcp

El endpoint MCP es:

http://127.0.0.1:8000/mcp

Usa TLS y autenticación frente al servidor antes de exponerlo fuera de una máquina/red de confianza.

Ejemplos de llamadas a herramientas

Analizar una captura de pantalla

{
  "images": ["/home/you/Pictures/screen.png"],
  "prompt": "What application is open, what is the current state, and what should I click next?",
  "detail": "original"
}

Lectura rápida y gruesa de pantalla

{
  "images": ["/home/you/Pictures/screen.png"],
  "prompt": "Is a modal dialog visible? Answer briefly.",
  "detail": "low"
}

OCR

{
  "image": "/home/you/Pictures/error.png",
  "detail": "original"
}

Localización de interfaz con el mejor esfuerzo

{
  "image": "/home/you/Pictures/screen.png",
  "target": "the blue Save button"
}

vision_locate devuelve coordenadas normalizadas de 0 a 1000. Se describe intencionalmente como de mejor esfuerzo: un VLM generativo no es un detector determinista. Valida su objetivo antes de clics de alto impacto.

Modelo de seguridad

Las imágenes analizadas por este MCP se envían a la API externa de DeepSeek. No envíes imágenes privadas o sensibles sin el consentimiento informado del usuario.

Las rutas locales están restringidas a DEEPSEEK_VISION_ALLOWED_ROOTS. Si no se configuran raíces, el servidor solo permite imágenes bajo su directorio de trabajo actual.

Esto importa: una herramienta sin restricciones del estilo vision_analyze("/etc/...") permitiría que un host MCP convirtiera el análisis de imágenes en exfiltración arbitraria de archivos locales.

El servidor también rechaza URLs externas obvias de localhost/IP privada.

El lanzador compartido pasa solo las variables de proceso base, XDG_* y las cuatro configuraciones aprobadas de DeepSeek al proceso hijo. Nunca carga un archivo de credenciales completo.

Comportamiento de imágenes de DeepSeek reflejado por este servidor

• JPEG, PNG, GIF, WebP

• imagen local/base64 en línea: máx. 32 MiB cada una

• imagen de la API de archivos de DeepSeek: máx. 64 MiB

• máx. 600 imágenes por solicitud

• longitud de URL externa: máx. 8192 caracteres

• dimensión máxima: 8192 px por lado, o 4096 px por lado para 15+ imágenes

• detail=low: DeepSeek reduce a 512x512

• detail=original / high: conserva el detalle original

• las imágenes solo se envían en el mensaje del usuario

Imágenes grandes/reutilizadas

Sube una vez:

{
  "local_path": "/home/you/Pictures/large.png",
  "expires_seconds": 86400
}

Luego pasa el ID file-api-... devuelto a vision_analyze. Usa null para expires_seconds solo cuando quieras intencionalmente almacenamiento permanente en DeepSeek.

Docker

docker build -t deepseek-vision-mcp .
docker run --rm \
  -p 127.0.0.1:8000:8000 \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  deepseek-vision-mcp

Para rutas de imagen locales en Docker, monta solo los directorios que el MCP necesita y establece DEEPSEEK_VISION_ALLOWED_ROOTS a la ruta del lado del contenedor.

Arquitectura

MCP host / agent
      |
      | MCP tool call
      v
DeepSeek Vision MCP
  - validates source
  - restricts local paths
  - encodes local files
  - shapes DeepSeek payload
      |
      | HTTPS
      v
api.deepseek.com
  deepseek-v4-flash-vision-exp
      |
      v
structured MCP result

Desarrollo

uv sync --locked --extra dev
uv run ruff check .
uv run pytest

CI ejecuta las mismas compuertas en Python 3.11 y 3.13. Las contribuciones y los informes de errores enfocados son bienvenidos.