deepseek-vision-mcp

<div align="center">

<img src="docs/assets/hero.svg" alt="DeepSeek Vision MCP - Local vision for every MCP client" width="100%" />

<br />

中文 · English

让任意 MCP 客户端调用本地 Ollama 多模态模型，快速理解你电脑上的图片。

</div>

[!TIP] 图片只在本机处理。服务会把图片直接发送给本地 Ollama，不经过第三方云服务，也不会生成临时图片文件。

模型说明： 项目名称保留 deepseek-vision-mcp，但服务并不绑定 DeepSeek 模型。默认使用 qwen3.5:2b，也支持其他 Ollama 视觉模型。

为什么用它

本地优先	即插即用	灵活选型
图片和推理都留在你的设备上	标准 MCP 工具，可接入兼容客户端	通过环境变量切换任意 Ollama 视觉模型

快速开始

1. 准备视觉模型

确保 Ollama 正在运行，然后拉取一个支持视觉的模型：

ollama pull qwen3.5:2b

也可以使用其他 Ollama 官方库中的视觉模型，例如 qwen3-vl:2b 或 gemma3:4b。

2. 安装项目

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

python -m venv .venv

<details> <summary><strong>激活虚拟环境</strong></summary>

macOS / Linux 激活方式

source .venv/bin/activate

Windows PowerShell 激活方式

.venv\Scripts\Activate.ps1

</details>

pip install -r requirements.txt

3. 接入 MCP 客户端

将下面的配置加入支持 MCP 的客户端。请把路径换成你电脑上 server.py 的绝对路径：

{
  "mcpServers": {
    "deepseek-vision": {
      "command": "python",
      "args": ["/absolute/path/to/deepseek-vision-mcp/server.py"]
    }
  }
}

配置完成后重启客户端，即可直接提出类似请求：

分析 /path/to/screenshot.png，告诉我页面上有哪些可用操作。

提供的工具

工具	用途	主要参数
analyze_image	描述图片内容，支持自定义提示词	file_path, prompt
analyze_image_with_question	针对图片回答一个具体问题	file_path, question
list_supported_models	查看本地已安装的 Ollama 模型	无

工作原理

flowchart LR
    A["MCP 客户端"] -->|"工具调用"| B["DeepSeek Vision MCP"]
    B -->|"读取本地图片"| C["Base64 编码"]
    C -->|"/api/generate"| D["本地 Ollama"]
    D -->|"视觉模型结果"| B
    B -->|"文本响应"| A

• 使用 stdio 与 MCP 客户端通信。
• 使用 Python 标准库 urllib 调用 Ollama /api/generate。
• 当 response 为空时，会回退读取 thinking 字段，兼容 Qwen3.5 的思考模式。
• 单张图片默认最大 20 MB，请求超时为 300 秒。

配置

环境变量	默认值	说明
OLLAMA_HOST	http://localhost:11434	Ollama 服务地址
OLLAMA_VISION_MODEL	qwen3.5:2b	默认视觉模型
OLLAMA_VISION_MAX_MB	20	单张图片大小上限，单位 MB

macOS / Linux

export OLLAMA_VISION_MODEL=qwen3-vl:2b
python server.py

Windows PowerShell

$env:OLLAMA_VISION_MODEL = "qwen3-vl:2b"
python server.py

常见问题

<details> <summary><strong>连接不到 Ollama</strong></summary>

先运行 ollama serve，再访问 http://localhost:11434/api/tags 检查服务是否正常。如果 Ollama 在另一台设备上，请设置 OLLAMA_HOST。

</details>

<details> <summary><strong>模型不支持图片</strong></summary>

运行 ollama list 查看已安装模型，并确认所选模型具备视觉能力。随后将模型名写入 OLLAMA_VISION_MODEL。

</details>

<details> <summary><strong>MCP 客户端没有显示工具</strong></summary>

确认配置中的 server.py 使用绝对路径，并确保配置使用的 Python 环境已经安装 fastmcp。修改配置后重新启动客户端。

</details>

参与贡献

欢迎提交问题和改进。开始开发前请阅读 贡献指南。

License

本项目基于 MIT License 开源。

<div align="center"> _{Local images. Local models. Standard MCP.} </div>