🖼️ MCP 图片理解服务器

基于 MCP (Model Context Protocol) 的图片理解服务器，让纯文本模型（如 Codex CLI / DeepSeek）也能看懂图片内容。

通过调用本地 Ollama 多模态模型（如 minicpm-o4.5）进行图片分析，无需调用任何云端视觉 API，数据完全本地处理。

✨ 功能

🔍 analyze_image — 分析单张图片，支持自定义提问
🆚 analyze_images — 多图（最多 5 张）对比分析
📝 ocr_image — 从图片中提取文字（支持中英文）
🔄 支持本地图片和 URL 图片

📋 前置要求

组件	说明
Python 3.10+	运行环境
Ollama	本地多模态模型服务
多模态模型	如 `minicpm-o4.5`、`llava`、`gemma3` 等

安装 Ollama 并拉取模型：

ollama pull minicpm-o4.5

🚀 快速开始

1️⃣ 安装依赖

方式一：运行脚本（推荐）

setup.bat

方式二：手动安装

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

2️⃣ 启动 Ollama（如未运行）

ollama serve

3️⃣ 配置 MCP JSON

在 MCP 客户端（如 Codex CLI / Claude Desktop / Cursor 等）的配置文件中，添加以下条目：

{
  "mcpServers": {
    "image-understanding": {
      "command": "python",
      "args": ["F:/path/to/my-image-server/run.py"],
      "env": {
        "OLLAMA_HOST": "http://localhost:11434",
        "VISION_MODEL": "minicpm-o4.5",
        "OLLAMA_TIMEOUT": "120"
      }
    }
  }
}

⚠️ 将 F:/path/to/my-image-server 替换为你项目所在的实际路径。

📁 不同客户端的配置位置

客户端	配置文件路径
Codex CLI	`~/.codex/config.json`
Claude Desktop	Settings → Developer → Edit Config → `claude_desktop_config.json`
Cursor	Settings → Features → MCP → Add new MCP server

⚙️ 环境变量

变量	默认值	说明
`OLLAMA_HOST`	`http://localhost:11434`	Ollama 服务地址
`VISION_MODEL`	`minicpm-o4.5`	使用的多模态模型名称
`OLLAMA_TIMEOUT`	`120`	请求超时时间（秒），大图片可适当调大

也可以直接在命令行中临时设置：

set OLLAMA_HOST=http://localhost:11434
set VISION_MODEL=llava
python run.py

🧩 提供的 MCP Tools

`analyze_image`

参数	类型	必填	说明
`image_path`	string	✅	本地路径或 URL
`question`	string	❌	针对图片的问题，默认"请详细描述这张图片的内容"

`analyze_images`

参数	类型	必填	说明
`image_paths`	string[]	✅	图片路径列表（最多 5 张）
`question`	string	❌	对比分析问题

`ocr_image`

参数	类型	必填	说明
`image_path`	string	✅	本地路径或 URL

💡 在对话中使用示例

> 分析这张图片：C:\photos\cat.jpg
> 对比这两张图有什么不同：img1.png 和 img2.png
> 提取这张截图里的所有文字：screenshot.png
> 这个网页截图里的按钮是做什么的？https://example.com/screenshot.png

🏗️ 项目结构

my-image-server/
├── run.py              # MCP 服务器主程序
├── requirements.txt    # Python 依赖
├── setup.bat           # Windows 环境初始化脚本
├── venv/               # Python 虚拟环境
└── README.md           # 本文件

📄 License

MIT

ollama-vision-mcp