deepseek-vision-mcp（Chinese README）

给无视觉能力的文本 LLM（如 DeepSeek）当「眼睛」的 MCP 服务器 —— 一个稳定、可替换后端的云端视觉适配层。

设计理念（四层分工）

• 主模型 = 大脑：解释、推理、判断、建议、任务决策
• Vision MCP = 眼睛：忠实描述「我看到了什么」
• Skill = 工作规范：特定领域的规则（不在此项目）
• Claude Code = 调度与执行：调工具、改文件、执行任务

本 MCP 只回答「我看到了什么」，不回答「这意味着什么」，不替主模型思考。

功能特性

• 双协议分流：OpenAI 兼容 Chat Completions（通用视觉模型）+ PaddleOCR 专用 OCR 协议
• 图片三段式处理：加载 → 校验 → 预处理（EXIF 校正、等比缩放）
• 内容寻址缓存（image_sha256）：重复分析同一张图秒回，省额度
• 临时错误自动重试（≤2 次指数退避）
• 失败透明：视觉服务失败时明确报错，绝不伪造结果

安装

需要 Python 3.11+ 和 uv。

uv sync

配置

所有配置通过环境变量注入（.mcp.json 的 env 或 .env）。

变量	说明	默认值
VISION_API_KEY	视觉 API 的 key	无，必填
VISION_API_BASE_URL	OpenAI 兼容 Chat 接口 base URL	无，必填
VISION_OCR_ENDPOINT	PaddleOCR 专用 OCR 接口完整地址	无（用 PaddleOCR 时填）
VISION_OCR_MODEL	mode=ocr 使用的模型	无，必填
VISION_FULL_MODEL	mode=full 使用的模型	无，必填
VISION_CACHE_ENABLED	缓存总开关	true
VISION_CACHE_SCOPE	global / project / none	global
VISION_CACHE_DIR	缓存目录覆盖（空=平台默认）	空
VISION_CACHE_TTL_DAYS	缓存有效期（天）	30
VISION_CACHE_MAX_SIZE_MB	缓存最大容量（MB）	128
VISION_FALLBACK_ENABLED	fallback 开关	false
VISION_RETRY_MAX	临时错误重试上限	2
VISION_TIMEOUT	单次 API 超时（秒）	60

参考 .env.example。

注册到 Claude Code

项目级（.mcp.json）或用户级（~/.claude.json 的 mcpServers）：

{
  "mcpServers": {
    "deepseek-vision-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/deepseek-vision-mcp", "deepseek-vision-mcp"],
      "env": {
        "VISION_API_KEY": "sk-...",
        "VISION_API_BASE_URL": "https://your-vision-api.example.com/v1",
        "VISION_OCR_ENDPOINT": "https://your-ocr-api.example.com/v1/paddleocr",
        "VISION_OCR_MODEL": "PaddleOCR-VL-1.5",
        "VISION_FULL_MODEL": "your-vision-model"
      }
    }
  }
}

若 uv 不在 PATH，command 用 uv 的完整路径。

Windows 示例（uv 通常不在 PATH，command 用完整路径，目录用正斜杠）：

{
  "mcpServers": {
    "deepseek-vision-mcp": {
      "command": "C:/Users/你的用户名/.local/bin/uv.exe",
      "args": ["run", "--directory", "D:/path/to/deepseek-vision-mcp", "deepseek-vision-mcp"],
      "env": {
        "VISION_API_KEY": "sk-...",
        "VISION_API_BASE_URL": "https://your-vision-api.example.com/v1",
        "VISION_FULL_MODEL": "your-vision-model"
      }
    }
  }
}

若 uv 通过其它方式安装（pipx / scoop / choco），把 command 指向对应的 uv.exe 路径即可。

使用

在对话里对主模型说：

• 「看下这张图 D:\xxx\chart.png」→ analyze_image(path, mode="full")
• 「把这张图的文字提取出来 D:\xxx\table.png」→ analyze_image(path, mode="ocr")

工具

analyze_image

• path_or_url：本地图片路径或 http(s) URL（PNG / JPEG / WEBP / GIF / BMP）
• mode："full"（默认，全面理解）或 "ocr"（仅提取文字）

如何添加新 Provider

1. 在 src/deepseek_vision_mcp/providers/ 新建文件，继承 base.Provider 并实现 analyze。
2. 在 router.py 的 get_provider 中按模型名（或其他判断）返回你的 Provider。
3. 完成，analyze_image 上层接口无需改动。

说明

本工具不提供视觉模型，只做「适配层」。你需要自带视觉 API 的 key。

License

MIT

deepseek-vision-mcp（English README）

An MCP server that acts as the "eyes" for text-only LLMs (such as DeepSeek) — a stable, provider-swappable cloud vision adapter layer.

Design Philosophy (Four Layers)

• Main model = Brain: interpret, reason, judge, advise, decide tasks
• Vision MCP = Eyes: faithfully describe "what I see"
• Skill = Work spec: domain-specific rules (not in this project)
• Claude Code = Orchestrator: call tools, edit files, execute tasks

This MCP only answers "what I see", not "what it means", and never thinks on behalf of the main model.

Features

• Dual-protocol routing: OpenAI-compatible Chat Completions (general vision models) + PaddleOCR dedicated OCR protocol
• Three-stage image pipeline: load → validate → preprocess (EXIF correction, aspect-ratio-preserving resize)
• Content-addressed cache (image_sha256): repeated analysis of the same image returns instantly
• Automatic retry on transient errors (≤2 attempts, exponential backoff)
• Failure transparency: reports errors clearly, never fabricates results

Installation

Requires Python 3.11+ and uv.

uv sync

Configuration

All configuration is injected via environment variables (.mcp.json env or .env).

Variable	Description	Default
VISION_API_KEY	Vision API key	none, required
VISION_API_BASE_URL	OpenAI-compatible Chat API base URL	none, required
VISION_OCR_ENDPOINT	PaddleOCR dedicated OCR endpoint (full URL)	none (set when using PaddleOCR)
VISION_OCR_MODEL	Model for mode=ocr	none, required
VISION_FULL_MODEL	Model for mode=full	none, required
VISION_CACHE_ENABLED	Cache switch	true
VISION_CACHE_SCOPE	global / project / none	global
VISION_CACHE_DIR	Cache dir override (empty = platform default)	empty
VISION_CACHE_TTL_DAYS	Cache TTL (days)	30
VISION_CACHE_MAX_SIZE_MB	Max cache size (MB)	128
VISION_FALLBACK_ENABLED	Fallback switch	false
VISION_RETRY_MAX	Max retries on transient errors	2
VISION_TIMEOUT	Per-request timeout (seconds)	60

See .env.example.

Registering with Claude Code

Project-level (.mcp.json) or user-level (mcpServers in ~/.claude.json):

{
  "mcpServers": {
    "deepseek-vision-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/deepseek-vision-mcp", "deepseek-vision-mcp"],
      "env": {
        "VISION_API_KEY": "sk-...",
        "VISION_API_BASE_URL": "https://your-vision-api.example.com/v1",
        "VISION_OCR_ENDPOINT": "https://your-ocr-api.example.com/v1/paddleocr",
        "VISION_OCR_MODEL": "PaddleOCR-VL-1.5",
        "VISION_FULL_MODEL": "your-vision-model"
      }
    }
  }
}

If uv is not on PATH, use the full path to uv for command.

Windows example (uv is usually not on PATH; use the full path for command and forward slashes for the directory):

{
  "mcpServers": {
    "deepseek-vision-mcp": {
      "command": "C:/Users/yourname/.local/bin/uv.exe",
      "args": ["run", "--directory", "D:/path/to/deepseek-vision-mcp", "deepseek-vision-mcp"],
      "env": {
        "VISION_API_KEY": "sk-...",
        "VISION_API_BASE_URL": "https://your-vision-api.example.com/v1",
        "VISION_FULL_MODEL": "your-vision-model"
      }
    }
  }
}

If uv is installed another way (pipx / scoop / choco), point command at the corresponding uv.exe.

Usage

Tell the main model:

• "Look at this image D:\xxx\chart.png" → analyze_image(path, mode="full")
• "Extract the text from this image D:\xxx\table.png" → analyze_image(path, mode="ocr")

Tool

analyze_image

• path_or_url: local image path or http(s) URL (PNG / JPEG / WEBP / GIF / BMP)
• mode: "full" (default, full understanding) or "ocr" (text extraction only)

Adding a New Provider

1. Create a new file under src/deepseek_vision_mcp/providers/, subclass base.Provider and implement analyze.
2. Return your provider from get_provider in router.py (keyed by model name or other criteria).
3. Done — the upper-level analyze_image tool needs no changes.

Note

This tool does not provide vision models; it is only an adapter layer. You need to bring your own vision API key.

License

MIT