Skip to main content
Glama
yunper-wang

mcp-image-analyzer

by yunper-wang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

MCP Image Analyzer

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

Node MCP License

为什么需要它？

很多强大的文本模型并不支持视觉输入（如 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，三种任选其一。

Related MCP server: image_mcp

核心特性

能力

🔒 安全

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

Available Tools

1 tool
analyze_imageA

使用多模态模型分析图片内容。支持本地文件路径、Base64 编码、或图片 URL。可用于识别图中文字、物体、场景、图表等。

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNo可选：覆盖默认模型（如 qwen-vl-plus 做快速 OCR，qwen-vl-max 做复杂分析）。留空用 OPENAI_MODEL。
detailNo图片解析精度（仅 OpenAI 官方端点生效）。auto=自动, low=低精度(更快), high=高精度。默认 auto。auto
promptNo对图片的分析指令，例如：'请描述这张图片的内容'、'提取图中的文字'、'这张图表说明了什么'。留空则默认描述。
image_urlNo图片的公网 URL 地址。与 image_path、image_base64 三选一。
image_pathNo本地图片文件的绝对路径（仅接受 PNG/JPEG/GIF/WebP/BMP）。与 image_base64、image_url 三选一。
image_base64No图片的 Base64 编码字符串（不含 data: 前缀）。与 image_path、image_url 三选一。

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

无注解，描述补充了输入格式和分析类型，但未说明返回的具体内容、模型选择（如 qwen-vl-plus vs qwen-vl-max）对结果的影响，也未提及三个图片来源必须互斥这一行为。描述对行为透明度的贡献一般。

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

描述仅两句话，第一句直接点明核心功能，第二句补充输入格式与用途，没有冗余信息，结构紧凑且前置信息充分。

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

工具结构简单，参数 schema 覆盖完整，但描述未提及必须提供一种图片来源、未说明返回值或输出形式，且无注解补充，对于无输出 schema 的工具略显不完整。

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema 描述覆盖率 100%，每个参数都有详细说明，描述本身没有额外解读参数，也没有需要补偿的缺口，故按基线 3 分评分。

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

描述明确说明使用多模态模型分析图片内容，动作和对象具体，并列出支持的文件路径、Base64、URL 三种输入方式及应用场景。尽管没有兄弟工具需要区分，但功能定位已经足够清晰。

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

描述清晰说明了适用于分析图片内容、识别文字/物体/场景/图表等场景，并列举了输入格式，提供了使用上下文。虽然没有明确排除场景或给出替代工具，但无兄弟工具时已算清晰。

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • First observedanalyze_image
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 1 tool

Disambiguation5/5

Only one tool exists, so there is no possibility of confusing it with others. The tool's purpose is clearly defined and distinct by default.

Naming Consistency5/5

The single tool name follows a consistent verb_noun pattern (analyze_image), which is clear and indicative of its function.

Tool Count4/5

A single tool is below the typical 3-15 range, but it is reasonable for a narrowly-focused image analysis server. It does not feel excessive or overly sparse given the server's specific purpose.

Completeness5/5

The tool covers all necessary input types (local, base64, URL) and a wide range of analysis capabilities (text, objects, scenes, charts), leaving no obvious gaps for the stated purpose of image analysis.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers