DeepSeek Vision MCP

A secure, lightweight MCP v2 server that gives any MCP-compatible agent DeepSeek V4 Flash Vision: image analysis, faithful descriptions, OCR, comparisons, UI/object localization, and reusable Files API uploads.

The server exposes the exact model deepseek-v4-flash-vision-exp without embedding provider-specific image payloads in every agent integration.

Tools

Tool	Purpose
vision_analyze	General one/multi-image analysis with a custom prompt
vision_describe	Faithful scene/UI description
vision_ocr	Screenshot/document OCR
vision_compare	Compare two or more images
vision_locate	Best-effort UI/object localization to normalized coordinates
vision_upload	Upload a local image to DeepSeek Files API
vision_files_list	List reusable uploaded images
vision_files_delete	Delete an uploaded image

Accepted image references:

• local server-side path
• public http:// or https:// URL
• data:image/...;base64,...
• DeepSeek file-api-... file ID

Why this server is thin

The MCP server does not run a local vision model. It only validates/normalizes image inputs and delegates inference to DeepSeek. That makes CPU/RAM usage tiny and lets any MCP-capable agent gain vision without embedding DeepSeek-specific payload shapes in the agent itself.

Install with 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

For a local MCP host, stdio is the preferred transport:

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

For development with MCP Inspector:

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

MCP host configuration

Typical stdio configuration:

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

Do not commit the API key. If the host can inherit environment variables, prefer injecting DEEPSEEK_API_KEY from your secret manager or shell.

Safe shared launcher

run-mcp.py is useful when several local agents share one installation. It:

• reads only approved DeepSeek variables from the process or an env file;
• filters unrelated inherited secrets before launching the MCP;
• forces stdio transport;
• restricts local images to explicit roots.

By default it reads ~/.hermes/.env and allows the usual image-working directories under the current home directory plus /tmp. Override those choices without editing the script:

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

Hermes configuration:

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

OpenCode configuration:

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

OMP and other standard MCP hosts can use the mcpServers example above with run-mcp.py as the command.

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

The MCP endpoint is:

http://127.0.0.1:8000/mcp

Use TLS and authentication in front of the server before exposing it outside a trusted machine/network.

Example tool calls

Analyze a screenshot

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

Fast coarse screen read

{
  "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 returns coordinates normalized to 0..1000. It is intentionally described as best-effort: a generative VLM is not a deterministic detector. Validate its target before high-impact clicks.

Security model

Images analyzed by this MCP are sent to DeepSeek's external API. Do not send private or sensitive images without informed user intent.

Local paths are restricted to DEEPSEEK_VISION_ALLOWED_ROOTS. If no roots are configured, the server only allows images under its current working directory.

This matters: an unrestricted vision_analyze("/etc/...") style tool would let an MCP host turn image analysis into arbitrary local-file exfiltration.

The server also rejects obvious localhost/private-IP external URLs.

The shared launcher passes only baseline process variables, XDG_*, and the four approved DeepSeek settings to the child process. It never sources an entire credentials file.

DeepSeek image behavior reflected by this server

• JPEG, PNG, GIF, WebP
• local/base64 inline image: max 32 MiB each
• DeepSeek Files API image: max 64 MiB
• max 600 images/request
• external URL length: max 8192 chars
• max dimension: 8192 px/side, or 4096 px/side for 15+ images
• detail=low: DeepSeek downsamples to 512x512
• detail=original / high: preserve original detail
• images are only sent in the user message

Large/reused images

Upload once:

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

Then pass the returned file-api-... ID into vision_analyze. Use null for expires_seconds only when you intentionally want permanent DeepSeek storage.

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

For local image paths in Docker, mount only the directories the MCP needs and set DEEPSEEK_VISION_ALLOWED_ROOTS to the container-side path.

Architecture

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

Development

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

CI runs the same gates on Python 3.11 and 3.13. Contributions and focused bug reports are welcome.