ollama-vision-mcp

为 Claude Code 中的 DeepSeek V4 Pro（无视觉能力）提供本地多模态视觉补充。通过 MCP Server + GUI 小工具 + Ollama 本地视觉模型，让纯文本大模型能够"看到"并分析代码截图、UI 截图、报错日志等图片内容。

你需要知道的事

这个项目由两部分组成：

| 组件 | 运行在哪 | 做什么 | |------|---------|------| | GUI 小工具 | Windows | 粘贴截图，生成图片 ID | | MCP Server | Windows 或 WSL | 接收 Claude Code 的调用，将图片发给 Ollama 视觉模型，返回文字描述 |

GUI 只能在 Windows 上运行（PySide6 桌面程序）。MCP Server 两者均可——如果你的 Claude Code 在 Windows 上，则MCP Server 也放 Windows；如果 Claude Code 在 WSL 里，则MCP Server 需要放 WSL。

环境要求（Windows 侧）

| 依赖 | 说明 | |------|------| | Python 3.11+ | Conda 管理，环境名 ollama-vision-mcp | | Ollama | 本地运行 ollama serve（默认 localhost:11434） | | VL 模型 | 至少安装一个，推荐 ollama pull gemma4:e2b + ollama pull qwen3-vl:4b-instruct-bf16 | | GPU | NVIDIA 显卡，约 10~20G VRAM |

方式 A：Windows Claude Code 用户（需要先走通这个）

1. 安装

备注：可以酌情调整克隆路径

git clone <repo-url> ollama-vision-mcp
cd ollama-vision-mcp
conda env create -f environment.yml
conda activate ollama-vision-mcp
ollama pull gemma4:e2b
ollama pull qwen3-vl:4b-instruct-bf16

2. 设置环境变量

需要设置一个必填环境变量。在 Windows 系统环境变量中添加：

| 变量 | 值 | 作用 | |------|-----|------| | VL_TOOL_POOL_DIR | C:\Users\HYMOD\.claude-images\pool（替换为你的用户名） | 图片存储目录 |

仅当conda不在系统PATH（终端输入conda --version无输出）时才需额外设置：

| 变量 | 值示例 | |------|--------| | VL_TOOL_CONDA_EXE | C:\ProgramData\anaconda3\Scripts\conda.exe |

推荐设置为系统环境变量，这样 GUI 启动脚本和 MCP Server 都能拿到。

3. 配置 .mcp.json

将项目根目录的 .mcp.json 复制到你的 Claude Code 工作区。文件内容：

QwenPaw（copaw）用户：此配置文件不能直接用于 copaw，需要额外调整。详见 docs/copaw-mcp-config.md。

{
  "mcpServers": {
    "vl-tool": {
      "command": "conda",
      "args": ["run", "--no-capture-output", "-n", "ollama-vision-mcp", "python", "mcp_server/server.py"],
      "env": {
        "VL_TOOL_POOL_DIR": "C:\\Users\\<你的用户名>\\.claude-images\\pool"
      }
    }
  }
}

将 <你的用户名> 替换为实际的 Windows 用户名。

也可以在 GUI 菜单 设置 → MCP 配置向导 一键生成并复制到剪贴板。

4. 启动 GUI

双击项目根目录的 start_gui.bat，启动 GUI 小工具。

5. 使用

1. 截图（Win+Shift+S / Snipaste / 微信截图等）
2. 在 GUI 窗口中 Ctrl+V 粘贴 → 获得图片 ID（如 vl_tool_20260504_015207_01）
3. 在 Claude Code 中说 "分析 vl_tool_20260504_015207_01"
4. DeepSeek 自动调用 visual_summary → 返回图片描述

如果需要更详细的分析，可以继续追问，DeepSeek 会调用 visual_analyze（支持指定模型、裁剪区域等）。

6. 验证

• 启动 GUI，粘贴截图 → 获得 ID
• Claude Code 中 "分析 " → 返回有意义的图片描述 → 安装成功
• 如果失败，查看 docs/faq.md 排查

方式 B：WSL Claude Code 用户

如果你的 Claude Code 运行在 WSL (Linux) 中，MCP Server 需要放在 WSL 侧。GUI 和 ollama 仍然在 Windows 侧运行（截图和粘贴在 Windows 上完成）。

前置：理解数据流

你截图 (Windows) → GUI (Windows) → 图片存入 Windows 侧 ~/.claude-images/pool/
                                                              ↓
WSL Claude Code → MCP Server (WSL) → 通过 /mnt/c/Users/... 读取 Windows 侧图片
                                  → 通过 localhost:11434 调用 Windows 侧 Ollama

1. WSL 中安装

备注：可以酌情调整克隆路径

# 在 WSL 终端中
cd ~
git clone <repo-url> ollama-vision-mcp
cd ollama-vision-mcp
conda env create -f environment.yml
conda activate ollama-vision-mcp

不需要在 WSL 中安装 Ollama 或下载模型——通过 localhost 自动转发到 Windows 侧。

当然，这就要求windows侧已经安装好ollama并且下载好模型。

2. 配置 .mcp.json

在 WSL 中编辑 ~/.claude/mcp.json：

{
  "mcpServers": {
    "vl-tool": {
      "command": "conda",
      "args": ["run", "--no-capture-output", "-n", "ollama-vision-mcp", "python", "/home/<你的WSL用户名>/ollama-vision-mcp/mcp_server/server.py"],
      "env": {
        "VL_TOOL_POOL_DIR": "/mnt/c/Users/<你的Windows用户名>/.claude-images/pool"
      }
    }
  }
}

关键点：

• args 中的路径指向 WSL 中的 server.py（不是 /mnt/... 路径）
• VL_TOOL_POOL_DIR 指向 Windows 侧的图片池（通过 /mnt/c/Users/... 挂载）
• localhost:11434 自动转发，无需配置网络

3. 启动 GUI（Windows 侧）

双击 start_gui.bat 启动 GUI。截图和粘贴操作与方式 A 完全一样。

4. 使用

与方式 A 的第 5 步相同。

验证安装

Windows 和 WSL 用户的验证方法相同：

1. 启动 GUI，粘贴截图 → 获得 ID
2. 在 Claude Code 中说 "分析 "
3. 如果 DeepSeek 返回了有意义的图片描述 → 安装成功

如果失败，查看 docs/faq.md。

环境变量速查

| 变量 | 必填 | 作用 | 设置位置 | |------|:--:|------|------| | VL_TOOL_POOL_DIR | 是 | 图片存储目录 | .mcp.json 的 env 或系统环境变量 | | VL_TOOL_CONDA_EXE | 否 | conda.exe 路径（仅在 conda 不在 PATH 时） | 系统环境变量 |

详见 docs/env-vars.md。

文档索引

| 文档 | 面向 | 内容 | |------|------|------| | docs/env-vars.md | 用户 | 环境变量详细说明 | | docs/faq.md | 用户 | 常见故障排查 | | docs/copaw-mcp-config.md | 用户 | QwenPaw (copaw) MCP 配置指南 | | docs/architecture.md | 开发者 | 架构全景、设计决策 | | docs/modules.md | 开发者 | 每文件接口与实现要点、新增模型 | | docs/testing.md | 开发者 | 测试方案、评测框架 | | claude.md | Agent | AI 编码助手快速参考 | | proposal.md | — | 原始设计文档 |