DeepSeek Vision MCP

Ein sicherer, schlanker MCP-v2-Server, der jedem MCP-kompatiblen Agenten DeepSeek V4 Flash Vision bietet: Bildanalyse, originalgetreue Beschreibungen, OCR, Vergleiche, UI-/Objektlokalisierung und wiederverwendbare Files-API-Uploads.

Der Server stellt exakt das Modell deepseek-v4-flash-vision-exp bereit, ohne anbieterspezifische Bild-Payloads in jede Agenten-Integration einzubetten.

Tools

Akzeptierte Bildreferenzen:

• lokaler serverseitiger Pfad

• öffentliche http://- oder https://-URL

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

• DeepSeek-file-api-...-Datei-ID

Related MCP server: vision-mcp

Warum dieser Server schlank ist

Der MCP-Server führt kein lokales Vision-Modell aus. Er validiert/normalisiert lediglich Bildeingaben und delegiert die Inferenz an DeepSeek. Dadurch ist der CPU-/RAM-Verbrauch minimal, und jeder MCP-fähige Agent kann Vision nutzen, ohne DeepSeek-spezifische Payload-Formen in den Agenten selbst einzubetten.

Installation mit 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

Für einen lokalen MCP-Host ist stdio der bevorzugte Transport:

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

Für die Entwicklung mit MCP Inspector:

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

MCP-Host-Konfiguration

Typische stdio-Konfiguration:

{
  "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"
      }
    }
  }
}

Den API-Schlüssel nicht einchecken. Wenn der Host Umgebungsvariablen erben kann, sollte DEEPSEEK_API_KEY bevorzugt aus dem Secret-Manager oder der Shell injiziert werden.

Sicherer gemeinsamer Launcher

run-mcp.py ist nützlich, wenn mehrere lokale Agenten eine Installation gemeinsam nutzen. Er:

• liest nur zugelassene DeepSeek-Variablen aus dem Prozess oder einer Env-Datei;

• filtert nicht verwandte geerbte Geheimnisse, bevor er den MCP startet;

• erzwingt den stdio-Transport;

• beschränkt lokale Bilder auf explizite Wurzelverzeichnisse.

Standardmäßig liest er ~/.hermes/.env und erlaubt die üblichen Bild-Arbeitsverzeichnisse unter dem aktuellen Home-Verzeichnis sowie /tmp. Diese Einstellungen können ohne Skriptbearbeitung überschrieben werden:

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

Hermes-Konfiguration:

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

OpenCode-Konfiguration:

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

OMP und andere Standard-MCP-Hosts können das obige mcpServers-Beispiel mit run-mcp.py als Befehl verwenden.

Streamable HTTP

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

Der MCP-Endpunkt ist:

http://127.0.0.1:8000/mcp

Vor der Bereitstellung außerhalb einer vertrauenswürdigen Maschine/Netzwerks sollten TLS und Authentifizierung vor dem Server eingesetzt werden.

Beispiel-Toolaufrufe

Screenshot analysieren

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

Schnelle grobe Bildschirmauslesung

{
  "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"
}

Best-Effort-UI-Grounding

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

vision_locate gibt Koordinaten zurück, die auf 0..1000 normalisiert sind. Es ist bewusst als Best-Effort beschrieben: Ein generatives VLM ist kein deterministischer Detektor. Das Ziel vor risikoreichen Klicks validieren.

Sicherheitsmodell

Bilder, die von diesem MCP analysiert werden, werden an die externe DeepSeek-API gesendet. Keine privaten oder sensiblen Bilder ohne informierte Nutzerabsicht senden.

Lokale Pfade sind auf DEEPSEEK_VISION_ALLOWED_ROOTS beschränkt. Wenn keine Wurzelverzeichnisse konfiguriert sind, erlaubt der Server nur Bilder unter seinem aktuellen Arbeitsverzeichnis.

Das ist wichtig: Ein uneingeschränktes vision_analyze("/etc/...")-artiges Tool würde es einem MCP-Host ermöglichen, Bildanalyse in willkürliche Exfiltration lokaler Dateien zu verwandeln.

Der Server lehnt außerdem offensichtliche Localhost-/Private-IP-Externe-URLs ab.

Der gemeinsame Launcher übergibt nur Basis-Prozessvariablen, XDG_* und die vier zugelassenen DeepSeek-Einstellungen an den Kindprozess. Er bezieht niemals eine gesamte Anmeldedatendatei.

Von diesem Server abgebildetes DeepSeek-Bildverhalten

• JPEG, PNG, GIF, WebP

• lokales/Base64-Inline-Bild: max. 32 MiB pro Bild

• DeepSeek-Files-API-Bild: max. 64 MiB

• max. 600 Bilder/Anfrage

• externe URL-Länge: max. 8192 Zeichen

• maximale Abmessung: 8192 px/Seite, oder 4096 px/Seite bei 15+ Bildern

• detail=low: DeepSeek verkleinert auf 512x512

• detail=original / high: Originaldetails beibehalten

• Bilder werden nur in der Benutzernachricht gesendet

Große/wiederverwendete Bilder

Einmal hochladen:

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

Dann die zurückgegebene file-api-...-ID an vision_analyze übergeben. null für expires_seconds nur verwenden, wenn absichtlich dauerhafte DeepSeek-Speicherung gewünscht ist.

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

Für lokale Bildpfade in Docker nur die Verzeichnisse einbinden, die der MCP benötigt, und DEEPSEEK_VISION_ALLOWED_ROOTS auf den Container-seitigen Pfad setzen.

Architektur

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

Entwicklung

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

CI führt dieselben Prüfungen auf Python 3.11 und 3.13 aus. Beiträge und fokussierte Fehlerberichte sind willkommen.