MCP Image Analyzer

给任意 LLM 装上「眼睛」——通过 MCP 协议调用 OpenAI 兼容的多模态模型分析图片，让 DeepSeek、Claude（非 vision 版）、本地大模型等不具备视觉能力的模型也能"看图"。

为什么需要它？

很多强大的文本模型并不支持视觉输入（如 DeepSeek-R1、Claude 非 vision 版、各类本地模型）。本服务作为中间层：接收图片 → 调用 OpenAI 兼容的多模态接口（如 qwen-vl-max、gpt-4o、glm-4v）→ 把分析结果回传给主模型，主模型即可基于"看到了什么"继续推理。

你的 LLM ──MCP──→ analyze_image ──→ OpenAI 兼容多模态 API
   ↑                                    (qwen-vl / gpt-4o / glm-4v)
   └────────── 分析结果（文字）←─────────────────┘

支持的图片来源：本地路径 · Base64 · 公网 URL，三种任选其一。

核心特性

	能力
🔒 安全	magic bytes 校验真实图片类型——拒绝读取 /etc/passwd、SSH 私钥等任意文件，防止通过 image_path 外泄敏感数据
⚡ 性能	sharp 大图自动降采样；显式 60s 超时；SDK 内置 429/5xx 自动重试；异步读盘不阻塞
🎯 简洁输出	内置 system prompt + max_tokens 控制，防止多模态模型输出冗长"小作文"
🔀 模型分级	调用时可用 model 参数临时换模型——快速 OCR 用 qwen-vl-plus（约 9× 快），复杂分析用 qwen-vl-max
🛡️ 健壮	配置缺失即退出（不当"僵尸"进程）；图片大小上限；结构化错误（附 HTTP 状态码）
🌐 多服务商	兼容阿里百炼 / OpenAI / 智谱等任意 OpenAI 兼容端点；OPENAI_API_VERSION 适配智谱 /v4 路径

快速开始

1. 克隆与安装

git clone https://github.com/yunper-wang/mcp-image-analyzer.git
cd mcp-image-analyzer
npm install

npm install 会装好 @modelcontextprotocol/sdk、openai、sharp（原生模块，按本机架构编译）。

2. 配置环境变量

最小配置三项必填，其余可选：

# 必填（在 MCP 客户端的 server env 中注入）
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode   # 不带 /v1，程序自动拼版本段
OPENAI_API_KEY=sk-你的密钥
OPENAI_MODEL=qwen-vl-max

# 可选
OPENAI_API_VERSION=v1          # OpenAI/阿里百炼用 v1；智谱用 v4
IMAGE_ANALYZER_MAX_TOKENS=1024  # 输出 token 上限
IMAGE_ANALYZER_TIMEOUT_MS=60000 # 单次请求超时(ms)
IMAGE_ANALYZER_MAX_IMAGE_MB=20  # 图片大小上限
IMAGE_ANALYZER_COMPRESS_THRESHOLD=1500000  # 解码后超此字节才压缩
IMAGE_ANALYZER_COMPRESS_MAX_EDGE=2048      # 压缩时长边上限
IMAGE_ANALYZER_SEND_DETAIL=0   # 仅 OpenAI 官方端点才开 detail 字段

💡 OPENAI_BASE_URL 不要带 /v1 后缀——程序会自动拼上 /<OPENAI_API_VERSION>，带 /v1 会拼成 /v1/v1 导致 404。即便误带，程序也会自动剥离兜底。

3. 接入 MCP 客户端

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "image-analyzer": {
      "command": "node",
      "args": ["/你的路径/mcp-image-analyzer/index.js"],
      "env": {
        "OPENAI_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode",
        "OPENAI_API_KEY": "sk-你的密钥",
        "OPENAI_MODEL": "qwen-vl-max"
      }
    }
  }
}

Cursor / 其他 MCP 客户端：参照上例，把 args 指向解压后的 index.js 绝对路径，env 注入同样的三项变量即可。详细多平台步骤见 INSTALL.md。

配置后重启客户端，analyze_image 工具即出现在工具列表中。

支持的模型服务商

任意 OpenAI 兼容的多模态端点都可用，常见配置：

服务商	OPENAI_BASE_URL	OPENAI_MODEL 示例	OPENAI_API_VERSION
阿里百炼 DashScope	https://dashscope.aliyuncs.com/compatible-mode	qwen-vl-max / qwen-vl-plus	v1（默认）
OpenAI 官方	https://api.openai.com/v1（可省略）	gpt-4o / gpt-4o-mini	v1
智谱 BigModel	https://open.bigmodel.cn/api/paas	glm-4v	v4

工具参数

analyze_image 工具的入参：

参数	类型	必填	说明
image_path	string	三选一	本地图片绝对路径（仅 PNG/JPEG/GIF/WebP/BMP）
image_base64	string	三选一	图片 Base64（不含 data: 前缀）
image_url	string	三选一	图片公网 URL
prompt	string	可选	分析指令，如"提取图中文字""描述这张图表"。留空则默认描述
detail	enum	可选	auto / low / high，默认 auto。仅 OpenAI 官方端点生效，兼容端点建议不开 SEND_DETAIL
model	string	可选	覆盖默认模型。如快速 OCR 传 qwen-vl-plus、复杂分析传 qwen-vl-max

示例调用（LLM 自动发起，也可在 MCP 客户端手动测试）：

{
  "image_path": "/abs/path/screenshot.png",
  "prompt": "提取图中所有可见文字"
}

{
  "image_url": "https://example.com/chart.png",
  "prompt": "这张折线图说明什么趋势？列出坐标轴和关键数值",
  "model": "qwen-vl-plus"
}

安全设计

这是本服务相对"裸调 API"的关键加固：

• magic bytes 校验：读取本地文件后，先按文件头字节判定是否为真实图片（PNG 89 50 4E 47、JPEG FF D8 FF 等），不是图片直接拒绝。这意味着攻击者无法通过 image_path 让模型读取并外泄 /etc/passwd、SSH 私钥、.env 等任意文件——即便这些文件能被 base64 编码。
• 大小上限：默认 20MB，超限拒绝，防止超大文件拖垮模型上下文或产生高额费用。
• 配置缺失即退出：三项必填变量缺任一，进程立即 exit(1) 并提示缺哪项，避免启动成静默失败的"僵尸"服务。
• 不含敏感信息：密钥仅从环境变量读取，源码中无任何硬编码凭据。

技术栈

• @modelcontextprotocol/sdk — MCP 协议实现（stdio 传输）
• openai — OpenAI 兼容客户端（超时 + 自动重试）
• sharp — 大图降采样（按需压缩，失败优雅降级）
• 纯 ESM，Node ≥ 18，零构建

项目结构

mcp-image-analyzer/
├── index.js              # MCP Server 主程序
├── package.json
├── package-lock.json
├── .env.example          # 配置模板（无真实密钥）
├── docs/
│   └── INSTALL.md        # 详细安装与多平台配置
├── SKILL.md              # 客户端无关使用说明
├── LICENSE
└── README.md

License

MIT