MCP 协议 · 开源

让 AI 看懂
你的截图

mcp_images 是一个轻量级 MCP 图片分析服务器，将本地图片、剪贴板截图或 Base64 数据发送至 VLM API，返回精准的结构化分析结果。

快速开始 → GitHub
核心功能

三种方式，一个目标

无论图片来自文件、剪贴板还是 Base64 编码，mcp_images 都能高效处理并交给 VLM 分析。

📁

describe_image_file

传入本地图片绝对路径，自动解码、处理、分析。支持 JPEG、PNG、BMP、TIFF、WebP 格式。

📋

describe_clipboard_image

直接读取系统剪贴板中的截图，无需保存文件。Windows 使用 Win32 API，Linux 使用 xclip/wl-paste，macOS 使用 osascript，WSL 环境下自动通过 PowerShell 访问 Windows 剪贴板。

🔤

describe_base64_image

接收 Base64 编码的图片数据，适用于 IDE 将对话中的图片以 Base64 形式传递的场景。

架构设计

精简、高效、可扩展

Go 单二进制 + stdio JSON-RPC，零依赖运行，与任何兼容 MCP 的 AI 工具无缝集成。

AI 工具
→
stdio JSON-RPC
→
图片处理
→
VLM API
→
结构化结果
⚡

高性能图片处理

draw.Draw 批量色彩转换 + Pix 直接操作，比逐像素 At/Set 快 5-10 倍。Lanczos 算法缩放，自动 EXIF 旋转。

🔄

智能重试机制

VLM 请求支持指数退避重试（最多 2 次），自动识别超时、429、5xx 等可重试错误，提升服务可靠性。

🔒

并发安全

writeMu 互斥锁保证 stdout 写入有序，goroutine + WaitGroup 管理请求生命周期，优雅关闭不丢响应。

快速开始

快速上手

编译、配置、启动，即可在 AI 工具中使用图片分析能力。支持两种配置格式：标准 mcp.json 通用格式（Claude Code / Cursor / Trae / Codex 等）和 opencode 专用格式。两者的关键区别在于 command 类型（字符串 vs 数组）和字段名（env vs environment）。

1. 编译 
# Windows
./build.ps1                  # 编译
./build.ps1 -Action test    # 运行测试
./build.ps1 -Action lint    # 代码检查
./build.ps1 -Action build-all # 跨平台编译

# Linux / macOS
make build      # 编译
make test       # 运行测试
make lint       # 代码检查
make build-all  # 跨平台编译

# 版本号从 VERSION 文件读取，也可通过 -Version 1.0.0 参数覆盖
# 通过 -ldflags 注入 version 和 buildTime
2. 配置 mcp.json — 标准格式 Claude Code / Cursor / Trae / Codex 等 AI 工具通用（参考项目根目录 mcp.json.example） 
// ---- 方案 A: Ollama（纯本地） ----
{
  "mcpServers": {
    "mcp_images": {
      "command": "/path/to/mcp_images",
      "env": {
        "VLM_API_BASE": "http://localhost:11434/v1/chat/completions",
        "VLM_MODEL": "qwen2.5vl:7b",
        "VLM_LOG_LEVEL": "warn",
        "VLM_TIMEOUT": "120"
      }
    }
  }
}

// ---- 方案 B: vLLM（纯本地） ----
{
  "mcpServers": {
    "mcp_images": {
      "command": "/path/to/mcp_images",
      "env": {
        "VLM_API_BASE": "http://localhost:8000/v1/chat/completions",
        "VLM_MODEL": "Qwen/Qwen2.5-VL-7B-Instruct",
        "VLM_LOG_LEVEL": "warn",
        "VLM_TIMEOUT": "120"
      }
    }
  }
}

// ---- 方案 C: 云端 API（阿里云 DashScope / OpenAI） ----
{
  "mcpServers": {
    "mcp_images": {
      "command": "/path/to/mcp_images",
      "env": {
        "VLM_API_BASE": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
        "VLM_MODEL": "qwen-vl-plus",
        "VLM_API_KEY": "sk-your-key",
        "VLM_LOG_LEVEL": "warn",
        "VLM_TIMEOUT": "120"
      }
    }
  }
}
3. 配置 opencode — 专用格式 仅 opencode 使用 command 数组 + environment，其他工具不兼容 
// ---- 方案 A: Ollama（纯本地） ----
{
  "mcpServers": {
    "mcp_images": {
      "command": ["/path/to/mcp-images-linux-amd64"],
      "environment": {
        "VLM_API_BASE": "http://localhost:11434/v1/chat/completions",
        "VLM_MODEL": "qwen2.5vl:7b",
        "VLM_LOG_LEVEL": "warn",
        "VLM_TIMEOUT": "120"
      }
    }
  }
}

// ---- 方案 B: vLLM（纯本地） ----
{
  "mcpServers": {
    "mcp_images": {
      "command": ["/path/to/mcp-images-linux-amd64"],
      "environment": {
        "VLM_API_BASE": "http://localhost:8000/v1/chat/completions",
        "VLM_MODEL": "Qwen/Qwen2.5-VL-7B-Instruct",
        "VLM_LOG_LEVEL": "warn",
        "VLM_TIMEOUT": "120"
      }
    }
  }
}

// ---- 方案 C: 云端 API（阿里云 DashScope / OpenAI） ----
{
  "mcpServers": {
    "mcp_images": {
      "command": ["/path/to/mcp-images-linux-amd64"],
      "environment": {
        "VLM_API_BASE": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
        "VLM_MODEL": "qwen-vl-plus",
        "VLM_API_KEY": "sk-your-key",
        "VLM_LOG_LEVEL": "warn",
        "VLM_TIMEOUT": "120"
      }
    }
  }
}
4. 在 AI 工具中使用 
# 直接对话即可
"帮我分析这个报错截图"
"看看剪贴板里的图片"
"这张 UI 截图有什么问题？"
配置参考

环境变量

所有配置通过环境变量传入。标准格式用 env 字段，opencode 用 environment 字段。

VLM_API_BASE 必填

VLM API 端点地址，需兼容 OpenAI chat/completions 格式。支持云端服务或本地 Ollama / vLLM。

"https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions"
"http://localhost:11434/v1/chat/completions"

VLM_MODEL 必填

视觉语言模型名称，需支持图片输入。

"qwen-vl-plus"
"llava:13b"

VLM_API_KEY 云端必填

API 认证密钥。本地服务（localhost / 127.0.0.1）可省略。

VLM_TIMEOUT 可选

VLM API 请求超时秒数，默认 60。处理大图或网络不稳定时建议增大。

"120"

VLM_LOG_LEVEL 可选

日志级别：debug / info / warn / error，默认 warn。日志输出到 stderr，不影响 MCP 通信。

兼容的 VLM 服务

阿里云 DashScope

qwen-vl-plus / qwen-vl-max，国内首选，延迟低。

Ollama 本地

llava / minicpm-v 等，零成本，数据不出本机。

OpenAI 兼容

任何兼容 OpenAI API 的视觉模型服务均可接入。

使用案例

从零搭建本地图片分析

以下以 Ollama + Qwen 视觉模型为例，演示如何零成本、数据不出本机地运行 mcp_images。量化后仅需 5-8GB 显存。

案例 A：Qwen2.5-VL 7B

量化后仅需约 5GB 显存，运行速度极快。中英文 OCR 优秀，识别代码和日志的准确度在轻量级模型中无可匹敌。

案例 B：Qwen3-VL 2B

量化后仅需约 3GB 显存，极致轻量。适合 UI 布局分析、简单图片描述等对速度要求更高的场景。

典型使用场景

🖥️

GPU 监控截图分析

直接截取任务管理器或 GPU 监控面板，AI 自动分析各指标使用率、瓶颈诊断，快速定位性能问题。

🐛

报错日志排查

终端或 IDE 报错截图一键分析，识别错误类型、堆栈关键信息，给出修复建议。IDE 内直接使用剪贴板工具，无需保存文件。

🎨

UI 设计稿评审

将 UI 设计稿截图交给 AI，自动分析布局结构、间距一致性、色彩搭配，输出可操作的改进建议。

📄

文档 / 白板 OCR

拍摄或截图文档、白板内容，AI 提取文字信息并结构化输出，支持中英文混合识别。

💻

代码截图提取

从演示视频、会议共享屏幕或 PDF 中截取代码片段，AI 提取并还原为可粘贴的代码文本。

🔍

数据可视化解读

将图表、仪表盘截图交给 AI，自动提取数据趋势、极值、异常点，生成文字总结报告。

Step 1 — 安装 Ollama 
# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows：从 https://ollama.com/download 下载安装包
Step 2 — 拉取视觉模型 
# 案例 A：高精度
ollama pull qwen2.5vl:7b

# 案例 B：轻量快速
ollama pull qwen3-vl:2b-instruct
Step 3 — 配置 mcp.json 
{
  "mcpServers": {
    "mcp_images": {
      "command": "/path/to/mcp_images",
      "env": {
        "VLM_API_BASE": "http://localhost:11434/v1/chat/completions",
        "VLM_MODEL": "qwen2.5vl:7b",
        "VLM_TIMEOUT": "120"
      }
    }
  }
}

# 本地部署无需 VLM_API_KEY，省略即可
Step 4 — 在 AI 工具中对话 
# 截图后直接问
"帮我看看这个报错是什么原因"
"分析一下剪贴板里的截图"

# 切换模型只需修改 VLM_MODEL
"VLM_MODEL": "qwen3-vl:2b-instruct"
技术细节

为什么选择 mcp_images

图片处理管线

  • ✓ 多格式解码：JPEG / PNG / BMP / TIFF / WebP
  • ✓ 自动 EXIF 方向校正
  • ✓ 色彩空间统一转换（draw.Draw 批量处理）
  • ✓ 智能缩放：超过 2048px 或 5MB 自动 Lanczos 降采样
  • ✓ 流式 Base64 编码，减少内存峰值

安全与可靠性

  • ✓ 路径遍历防护，禁止 .. 和相对路径
  • ✓ 文件大小限制（20MB）防止 OOM
  • ✓ VLM 请求指数退避重试（最多 2 次）
  • ✓ 并发安全：writeMu 保证响应有序
  • ✓ 优雅关闭：5s 超时等待进行中请求完成