Vision MCP

让原本不具备视觉能力的纯文本模型，通过 MCP（Model Context Protocol）调用云端多模态模型，获得图像理解、图像问答、OCR、图像处理等视觉能力。

纯文本 LLM 无法直接"看"图，但可以通过 MCP 把这个 server 暴露成工具：

文本模型 ──MCP调用──▶ vision-mcp ──▶ OpenAI / Gemini / Claude（多模态 API）
                        │
                        ├──▶ 图像理解（描述、问答、OCR）
                        └──▶ 图像处理（缩放、裁剪、旋转、转换、压缩、滤镜）

功能

工具	说明
`vision_status`	服务器状态、当前 provider / 模型、配置告警
`describe_image`	详细描述图像内容
`ask_image`	针对图像的任意自然语言问答
`ocr_image`	提取图中文字（OCR）
`process_image_tool`	本地处理：resize / crop / rotate / flip / convert / compress + 滤镜与亮度增强

快速开始

1. 克隆并安装

git clone <your-repo-url> vision-mcp
cd vision-mcp
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt    # Windows
# source .venv/bin/pip install -r requirements.txt  # macOS / Linux

2. 配置 API Key

复制 .env.example 为 .env，填入后端 API key：

VISION_PROVIDER=openai            # openai | gemini | anthropic
OPENAI_API_KEY=sk-...
# 若使用 OpenAI 兼容端点（智谱 / DeepSeek 等）：
# OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
# OPENAI_VISION_MODEL=glm-4.6v-flash

只用你选择的 provider 对应的 key 即可。

3. 注册到 Claude Code

在 ~/.claude.json 或项目 .mcp.json 中添加：

{
  "mcpServers": {
    "vision-mcp": {
      "command": "path/to/vision-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "vision_mcp.server"],
      "cwd": "path/to/vision-mcp"
    }
  }
}

4. （可选）上传图片自动分析

将 image_attach_hook.py 作为 UserPromptSubmit hook 注册到 ~/.claude/settings.json：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "path/to/vision-mcp/.venv/Scripts/python.exe path/to/vision-mcp/image_attach_hook.py",
            "timeout": 90
          }
        ]
      }
    ]
  }
}

上传图片时，hook 自动调用 describe_image + ocr_image，将视觉分析结果注入上下文——文本模型无需手动调用即可获得图片内容。

5. 手动测试

.venv\Scripts\python -m vision_mcp.server --help
# 或直接起 stdio 服务：
.venv\Scripts\python -m vision_mcp.server

图像路径约定

传绝对路径；或
传相对路径，并设置 VISION_IMAGE_BASE_DIR 指向图片目录；
也可以直接传 data: URI（例如处理工具产出的结果）。

技术架构

vision_mcp/
├── config.py       # 多 provider 配置（OpenAI / Gemini / Anthropic）
├── vision.py       # 视觉后端：图像理解、问答、OCR
├── image.py        # 图片加载、预处理、格式转换
├── processor.py    # 本地图像处理（resize/crop/rotate/滤镜等）
├── server.py       # MCP 服务入口，注册 5 个工具
└── __init__.py

image_attach_hook.py # UserPromptSubmit hook：上传图片自动分析
run_vision_mcp.bat    # Windows 启动脚本
e2e_test.py           # 端到端测试脚本
requirements.txt      # Python 依赖

许可

MIT