deepseek-vision-mcp

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

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

特性

• MCP 工具：analyze_design（设计稿 → 结构化规格/代码）、ask_vision（通用图片问答）
• CLI 模式：不接 MCP 也能把图片转成文字
• Codex Skill + 一键安装脚本
• 配置通过 .env / 环境变量管理，不写死在代码里
• 兼容 Hugging Face Router、OpenRouter、Ollama 等 OpenAI 兼容接口

工作原理

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

推荐模型

模型	许可证	适合场景	说明
Qwen/Qwen3-VL-8B-Instruct	Apache-2.0	设计稿识别、OCR、界面理解、转代码	推荐默认，8B 尺寸在 API 和本地都实用
Qwen/Qwen2.5-VL-7B-Instruct	Apache-2.0	成熟稳定的替代方案	各托管平台支持更广，作为兜底
ByteDance-Seed/UI-TARS-1.5-7B	Apache-2.0	GUI 理解、元素定位、UI 自动化	偏向“看界面并操作”，写代码不如 Qwen-VL
Qwen/Qwen3-VL-4B-Instruct	Apache-2.0	本地轻量运行	量化后占用小，适合内存有限的机器

快速开始

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

编辑 .env，至少设置 HF_TOKEN 或 VISION_API_KEY，然后测试：

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

配置说明

变量	必填	默认值	说明
HF_TOKEN	与 VISION_API_KEY 二选一	无	Hugging Face Token
VISION_API_KEY	与 HF_TOKEN 二选一	无	OpenAI 兼容服务的 API Key
VISION_API_BASE	否	https://router.huggingface.co/v1	OpenAI 兼容 API 地址
VISION_MODEL	否	Qwen/Qwen3-VL-8B-Instruct	视觉模型 ID
VISION_PROXY	否	无	代理地址，例如 http://127.0.0.1:7890
VISION_TIMEOUT_MS	否	120000	请求超时（毫秒）
VISION_MAX_TOKENS	否	4096	最大输出 token

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

CLI 用法

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

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 的绝对路径，环境变量同上。

接入 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。
• DeepSeek 官方 App 不支持 MCP：用 CLI 把图片转成文字后粘贴，或使用支持 MCP 的客户端。

License

MIT