ollama-vision-mcp

英文 · 中文

一个极简桥接服务，为只能使用纯文本模型（例如 DeepSeek）的 VS Code Copilot 提供本地视觉能力。

当 Copilot 使用纯文本模型时，它无法直接“看到”图像。这个 MCP 服务器弥补了这一缺口：你将截图放入文件夹；Copilot 通过该桥接读取图像 → 将其发送到本地 Ollama 视觉模型 → 得到文本描述，纯文本模型即可理解。

VS Code Copilot Chat (Agent mode, text-only model)
        │  MCP stdio
        ▼
ollama-vision-mcp (this package)
        │  Read local image → base64 → POST /v1/chat/completions
        ▼
Ollama (local vision model, e.g., qwen2.5vl:7b)

工具

Related MCP server: Hybrid Vision MCP Server

本工具范围

本包仅是一个桥接层。它完全通过 HTTP 与 Ollama 通信（OpenAI 兼容的 /v1/chat/completions 和 /v1/models）。

它不处理：

• 安装 Ollama、启动 ollama serve、拉取模型或管理模型配置；

• 访问剪贴板、IDE 内部机制，或除本地 Ollama 之外的任何网络服务。

你需自行负责安装 Ollama 和拉取模型（参见“先决条件”）。

先决条件

你必须自行完成以下设置：

• Python 3.10+

• Ollama 已安装并运行：ollama serve

• 至少已拉取一个视觉模型；推荐：

  bash

  ollama pull qwen2.5vl:7b

  其他选项：qwen3-vl:8b、gemma3:12b、llama3.2-vision:11b、llava:7b。 选择适合你 GPU 的模型；稍后通过 VISION_MCP_MODEL 环境变量指定。

🚀 快速安装（推荐）

在仓库根目录运行一条命令即可完成安装和配置：

bash

cd ollama-vision-mcp
python setup_mcp.py

该脚本将自动：

1. 创建专用虚拟环境（.venv）并安装本包（不污染全局环境）。

2. 检测本地 Ollama 服务并列出可用的视觉模型。

3. 交互式引导你设置 base_url、model、inbox、max_tokens、图像压缩以及可选的 API Key。

4. 将配置写入项目的 .vscode/mcp.json 和/或用户级全局 MCP 文件（%APPDATA%\Code\User\mcp.json），合并现有设置，不覆盖你的其他 MCP 服务器。

非交互式用法（适用于 CI/脚本）：

bash

python setup_mcp.py --yes --project --model qwen2.5vl:7b
python setup_mcp.py --print         # Only prints the config JSON, does not write to file

安装后，在 VS Code 中重新加载窗口（Ctrl+Shift+P → “Developer: Reload Window”）以使配置生效。

如果你以前运行过，也可以直接使用命令 ollama-vision-setup 重新配置。

验证安装

在 VS Code Copilot Chat（Agent 模式）中输入：

text

Run vision_status

如果返回的 JSON 包含 "ollama": { "ok": true, ... } 和模型列表，则连接成功。 如果 ok 为 false，请先启动 Ollama（ollama serve）再重试。

使用方法

1. 将截图放入项目的 inbox 目录（默认为 .ai/inbox）。服务器会在需要时自动创建该目录。

2. 在 Copilot Chat 中提问，例如：

   “查看 inbox 中的截图，告诉我这个错误是关于什么的。”

3. Agent 将自动调用 list_images → describe_image，并根据文本描述进行回答。

让 Agent 更智能（可选）：将现成的指令文件 .github/instructions/ollama-vision/vision-tools.instructions.md 复制到项目中的相同路径。它教会 Agent 完整的视觉工作流——调用顺序（list_images → describe_image → extract_text）、模式选择、故障排查，以及引导你将截图放入 inbox。作为 VS Code 的文件指令，只要任务涉及图像，它就会按需被发现，因此开箱即用，无需设置。

环境变量参考

兼容别名：VISION_MODEL、VISION_BASE_URL、VISION_INBOX、VISION_API_KEY。

手动安装（备选）

如果你需要完全手动控制每一步，请参考以下流程。

1. 创建环境并安装

bash

cd ollama-vision-mcp
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate    # macOS / Linux
pip install -e .

安装后，你会得到两个命令：

• ollama-vision-mcp — 启动 MCP 服务器

• ollama-vision-setup — 交互式配置快捷方式

2. 注册到 VS Code

将以下内容复制到项目的 .vscode/mcp.json（仅项目）或用户级文件 %APPDATA%\Code\User\mcp.json（所有项目）中。确保将 command 改为你的虚拟环境 Python 解释器的绝对路径：

json

{
  "servers": {
    "ollama-vision": {
      "type": "stdio",
      "command": "D:/MyRepos/ollama-vision-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "ollama_vision_mcp"],
      "env": {
        "VISION_MCP_BASE_URL": "http://localhost:11434/v1",
        "VISION_MCP_MODEL": "qwen2.5vl:7b",
        "VISION_MCP_INBOX": ".ai/inbox"
      }
    }
  }
}

⚠️ command 必须是虚拟环境内 Python 解释器的绝对路径。 你也可以运行 ollama-vision-setup --project 自动生成此文件。 服务器在调用时使用 os.getcwd()，因此相对路径（如 path 和 inbox 目录）将相对于服务器启动时的项目根目录来解析。

冒烟测试

运行以下脚本以检查 Ollama 连接、列出 inbox 内容，并对第一张图像执行真实的视觉调用：

bash

python examples/smoke_test.py

许可证

MIT