deepseek-vision-mcp

给 DeepSeek（以及 Codex、Claude Desktop、Cursor 等 MCP 客户端）增加“看图”能力的服务。

DeepSeek 的文本模型不接受图片输入。本项目把设计稿/UI 截图交给 Hugging Face 在线服务或本地 Ollama 上的开源视觉模型，返回结构化文字规格，再由 DeepSeek 或 Codex 完成前端代码实现。

特性

• MCP 工具：analyze_design（设计稿 → 结构化规格/代码）、ask_vision（通用图片问答）

• CLI 模式：不接 MCP 也能把图片转成文字

• Codex Skill + 一键安装脚本

• 配置通过 .env / 环境变量管理，不写死在代码里

• 兼容 Hugging Face Router、OpenRouter 等 OpenAI 兼容接口

• 本地 Ollama 原生支持，自动处理 Qwen3-VL 思考版 /no_think

Related MCP server: vision-mcp

工作原理

设计稿图片
   │
   ▼
deepseek-vision MCP 服务（本仓库）
   │  通过 OpenAI 兼容接口发送图片
   ▼
开源视觉模型（Hugging Face 或本地 Ollama，默认 Qwen3-VL-8B）
   │  返回结构化设计规格 / 代码草稿
   ▼
DeepSeek 或 Codex 拿到文字结果，结合项目写最终代码

推荐模型

本地 Ollama

无需 API Key。先启动 Ollama 并拉取模型：

ollama serve
ollama pull qwen3-vl:8b

在 .env 中启用本地 Ollama：

VISION_PROVIDER=ollama
OLLAMA_API_BASE=http://127.0.0.1:11434
OLLAMA_MODEL=qwen3-vl:8b

测试：

node cli.js examples/sample-design.png --mode spec --stack html+css

qwen3-vl:8b 是思考版，服务会自动应用 /no_think workaround，避免 token 被思考过程占满后返回空内容。追求更快更稳定可以：

ollama pull qwen3-vl:8b-instruct

然后把 OLLAMA_MODEL 改成 qwen3-vl:8b-instruct。

本地推理较慢时，Ollama 路径默认超时为 300 秒，可继续用 VISION_TIMEOUT_MS 调整。

快速开始

git clone <你的仓库地址>
cd deepseek-vision-mcp
npm install
cp .env.example .env

编辑 .env。使用在线服务时至少设置 HF_TOKEN 或 VISION_API_KEY；只使用本地 Ollama 时按上面「本地 Ollama」配置即可。然后测试：

node cli.js examples/sample-design.png --mode both --stack html+css

配置说明

所有配置都可以写在仓库根目录的 .env，服务会自动读取；也可以直接用环境变量覆盖。

CLI 用法

node cli.js 设计稿.png --mode both --stack react+tailwind
node cli.js 设计稿.png --mode spec
node cli.js 截图.png --question "这个页面的主色和布局结构是什么？"
node cli.js 设计稿.png --provider ollama --model qwen3-vl:8b --mode both --stack vue3+tailwind

CLI 输出是纯文字，可以直接复制给 DeepSeek 官方 App / 网页版。

MCP 接入（其他客户端）

Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "deepseek-vision": {
      "command": "node",
      "args": ["<项目绝对路径>/server.js"],
      "env": {
        "HF_TOKEN": "hf_xxx",
        "VISION_MODEL": "Qwen/Qwen3-VL-8B-Instruct"
      }
    }
  }
}

Cursor 的 .cursor/mcp.json 使用同样的结构。

Cherry Studio：设置 → MCP 服务器 → 添加，命令填 node，参数填 server.js 的绝对路径，环境变量同上。

本地 Ollama 的 MCP 环境变量示例：

{
  "mcpServers": {
    "deepseek-vision": {
      "command": "node",
      "args": ["<项目绝对路径>/server.js"],
      "env": {
        "VISION_PROVIDER": "ollama",
        "OLLAMA_API_BASE": "http://127.0.0.1:11434",
        "OLLAMA_MODEL": "qwen3-vl:8b"
      }
    }
  }
}

接入 Codex

详细步骤见 docs/CODEX.md。一键安装：

bash scripts/install.sh

脚本会安装 npm 依赖、把 Codex Skill 安装到 ~/.codex/skills/，并在本机有 codex CLI 时自动注册 MCP 服务。安装完成后重启 Codex，给一张设计稿图片说“按这张图实现前端”即可。

测试

npm test

仓库自带端到端冒烟测试，会启动 mock 视觉 API，验证 MCP 握手、工具注册和图片发送链路。

常见问题

• HTTP 401：HF_TOKEN / VISION_API_KEY 未配置或无效。

• 模型不可用：切换 VISION_MODEL，或更换 VISION_API_BASE（OpenRouter、Ollama 等）。

• 网络受限：设置 VISION_PROXY。

• 本地 Ollama 报连接失败：先运行 ollama serve。

• Ollama 返回内容为空：qwen3-vl:8b 思考版可能吃光 VISION_MAX_TOKENS，调大上限或改用 qwen3-vl:8b-instruct。

• DeepSeek 官方 App 不支持 MCP：用 CLI 把图片转成文字后粘贴，或使用支持 MCP 的客户端。

License

MIT