# deepseek-vision-mcp

一个本地 stdio MCP 服务器：让**没有视觉能力的主模型**（如 deepseek-v4-pro）通过调用视觉模型（deepseek-v4-flash）来"看图"。

## 为什么需要它

deepseek-v4-pro 本身不支持图片输入。当会话中需要理解截图、图表、照片等内容时，主模型调用本 MCP 的 `analyze_image` 工具：工具读取本地图片（或直接透传 URL），交给 DeepSeek 官方 API 的视觉模型分析，把文字结果返回给主模型。

## 目录结构

```
├── src/index.ts          # MCP 服务器 + analyze_image 工具 + 核心 analyzeImages 函数
├── scripts/smoke.mjs     # 冒烟测试（错误路径 + 真实 API 调用）
├── package.json
└── tsconfig.json
```

## 安装与构建

要求 Node.js ≥ 18（开发机已装 Node 24）。

```bash
cd C:\Project\deepseek-vision-mcp
npm install
npm run build          # 编译输出到 dist/index.js
```

## 注册到 Claude Code

```bash
claude mcp add deepseek-vision \
  --env DEEPSEEK_API_KEY=sk-你的key \
  -- node C:\Project\deepseek-vision-mcp\dist\index.js
```

注册后重启会话，用 `claude mcp list` 确认连接状态。

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
| `DEEPSEEK_API_KEY` | 是 | — | DeepSeek API key |
| `DEEPSEEK_BASE_URL` | 否 | `https://api.deepseek.com` | OpenAI 兼容 API 地址，可指向中转站 |
| `DEEPSEEK_VISION_MODEL` | 否 | `deepseek-v4-flash` | 视觉模型名，按实际可用模型修改 |

## 使用方式

会话中把图片路径告诉主模型并提问即可，主模型会根据工具描述自动调用：

> 帮我看看 C:\Users\asus\Pictures\screenshot.png 这张图里有什么

支持 1~4 张图片（本地绝对路径或 http(s) URL），每张 ≤ 20MB，格式 png/jpg/jpeg/webp/gif。也可以直接要求对比多张图片或做 OCR。

## 测试

```bash
npm run smoke
```

- 错误路径（无需 key）：空问题、文件不存在、坏扩展名、超 20MB、超过 4 张
- 真实 API（需 `DEEPSEEK_API_KEY` 在环境变量中）：用内置 1×1 PNG 调视觉模型并打印回答

## 常见错误

| 现象 | 原因与处理 |
|---|---|
| HTTP 401 - Invalid API key | `DEEPSEEK_API_KEY` 错误，重新 `claude mcp add` 注入 |
| HTTP 404 - model not found | 模型名不存在，改 `DEEPSEEK_VISION_MODEL` |
| HTTP 413 / 图片太大 | 压缩图片或改用更小的图 |
| 未配置 DEEPSEEK_API_KEY | 注册 MCP 时没有带 `--env DEEPSEEK_API_KEY=...` |
| 读取图片失败 | 路径写错或不存在；Windows 路径注意反斜杠 |

## 手动验证 API（不用 MCP）

```bash
curl https://api.deepseek.com/chat/completions ^
  -H "Content-Type: application/json" ^
  -H "Authorization: Bearer sk-你的key" ^
  -d "{\"model\":\"deepseek-v4-flash\",\"messages\":[{\"role\":\"user\",\"content\":[{\"type\":\"text\",\"text\":\"图里有什么？\"},{\"type\":\"image_url\",\"image_url\":{\"url\":\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"}}]}]}"
```