<div align="center">

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

<br />

**中文** · [English](README.en.md)

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

[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/Protocol-MCP-00A67E)](https://modelcontextprotocol.io/)
[![Ollama](https://img.shields.io/badge/Runtime-Ollama-white?logo=ollama&logoColor=black)](https://ollama.com/)
[![License](https://img.shields.io/github/license/kgamv/deepseek-vision-mcp?color=111827)](LICENSE)
[![Stars](https://img.shields.io/github/stars/kgamv/deepseek-vision-mcp?style=flat&color=F59E0B)](https://github.com/kgamv/deepseek-vision-mcp/stargazers)

</div>

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

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

## 为什么用它

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

## 快速开始

### 1. 准备视觉模型

确保 [Ollama](https://ollama.com/) 正在运行，然后拉取一个支持视觉的模型：

```bash
ollama pull qwen3.5:2b
```

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

### 2. 安装项目

```bash
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 激活方式

```bash
source .venv/bin/activate
```

#### Windows PowerShell 激活方式

```powershell
.venv\Scripts\Activate.ps1
```

</details>

```bash
pip install -r requirements.txt
```

### 3. 接入 MCP 客户端

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

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

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

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

## 提供的工具

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

## 工作原理

```mermaid
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

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

### Windows PowerShell

```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>

## 参与贡献

欢迎提交问题和改进。开始开发前请阅读 [贡献指南](CONTRIBUTING.md)。

## License

本项目基于 [MIT License](LICENSE) 开源。

<div align="center">
  <sub>Local images. Local models. Standard MCP.</sub>
</div>