image-viewer-mcp

一个用 Node.js 编写的 MCP 服务器。它接收图片的本地路径或 URL，把图片交给视觉语言模型（VLM）识别内容，返回三段结构化的描述，让只看得见文字的 LLM 也能完整理解图片。

背景

纯文本的 LLM 看不到图片。如果需要让它在对话中理解一张截图、一张图表或一张照片，常见的做法是借助外部视觉模型代为描述。本项目以 MCP 工具的形式提供这种能力，任何支持 MCP 的客户端（如 Claude Code、Claude Desktop）都可以直接调用。

Related MCP server: vision-mcp

功能

• 输入：本机图片的绝对路径、http(s) 图片 URL，或 data: 内联图片 URL

• 可选输入：图片背景信息（context），帮助模型更精准地识别

• 输出：三个字段，按工具调用的结构化结果返回

• 返回格式可切换：text（可读文本）、json（JSON 字符串）、raw（VLM 原始输出），默认取配置 output.format，调用时可用 format 参数覆盖

• 识别缓存：按图片内容 hash 复用识别结果，同图同配置直接返回缓存，节省 API 调用；默认启用，调用时可用 use_cache 参数控制

• 支持格式：PNG / JPG / JPEG / GIF / WEBP / AVIF / SVG，单张不超过 20MB

  • SVG 在服务端用 @resvg/resvg-js 自动转成 PNG 后再送模型，调用方无感（本地 SVG 文件或 SVG URL 均可）；尺寸过小（<14px）的 SVG 会自动放大到模型可读

  • AVIF 在服务端用 sharp 自动转码为 PNG 再送模型，不依赖模型侧对 AVIF 的支持

  • 过小的位图（如 icon）按整数倍自动放大到模型可读尺寸，避免被模型拒绝

• 后端默认使用 OpenAI 的 gpt-4o 视觉模型，可通过配置更换模型或改用任何兼容 OpenAI 协议的服务

工作原理

flowchart LR
    A[客户端调用 analyze_image] --> B{图片来源}
    B -->|本地路径| C[读取文件，按扩展名识别 MIME]
    B -->|http URL| D[下载图片，按响应头识别 MIME]
    B -->|data URL| E[解析内联 base64]
    C --> F[base64 编码]
    D --> F
    E --> F
    F --> G[组装多模态消息]
    G --> H[调用 VLM 接口]
    H --> I[解析三段 XML 标签]
    I --> J[返回 brief / description / summary]

安装

要求 Node.js 18 或更高版本。

npm install

配置

配置有两种方式：config.yaml 配置文件和环境变量。环境变量的优先级高于配置文件，便于在 MCP 客户端（如 Claude Code）中直接注入 Key。

优先级从高到低：环境变量 > config.yaml > 内置默认值。

配置文件

复制 config.example.yaml 为 config.yaml，按需修改。config.yaml 已被 .gitignore 忽略，不会入库，可安全存放 API Key。

查找位置：默认在 src/index.js 所在目录的上一级（即项目根目录）查找 config.yaml，与启动服务器时的工作目录无关。也可以把配置文件放到任意位置，用 --config <路径> 参数或 CONFIG_PATH 环境变量指定；这两种方式给出的相对路径按当前工作目录解析。

除 api_key 外所有字段均可选，未写的字段使用内置默认值。完整字段如下：

提示词配置

prompts 段控制发给 VLM 的全部提示词。三段输出的标签（tag）、标题（heading）、可读名称（label）均可自定义；用户提示词由配置自动生成，修改 tag 后提示词与解析器自动同步，不需要改两处。

prompts:
  system: |                      # 系统提示：约束角色、输出语言与回答纪律
    你是一个专业的图片内容识别助手。只依据图片和给定的背景信息进行描述，
    不虚构图片中不存在的细节。必须使用中文回答。
  instruction: |                 # 指令：紧跟图片发送，说明任务目标
    详细描述图片内容，目标是让仅能看到文字的LLM能够完全理解图片内容。
    回答格式：
  context_label: "图片背景信息（仅作参考）："   # 附加 context 参数时的引导语
  require_all_sections: true     # true 时任何一段缺失都按格式违规；false 时缺失段落留空
  sections:                      # 三段输出配置；key 固定，可只写想改的段，其余继承默认值
    - key: brief                 # 与工具输出字段对应
      tag: image_brief           # 模型回答中的包裹标签，解析器按此提取
      heading: 简要描述图片       # 提示词中该段的占位说明
      label: 简要                # 可读文本中该段的名称
    - key: description
      tag: image_description
      heading: 详细描述图片
      label: 详细
    - key: summary
      tag: image_summary
      heading: 总结图片意图/潜在含义/代表意义等
      label: 总结

环境变量

缺少 API Key 时服务器会拒绝启动并给出明确提示。

在 Claude Code 中使用

在 ~/.claude.json 或项目的 .mcp.json 中添加以下配置：

{
  "mcpServers": {
    "image-viewer": {
      "command": "node",
      "args": ["/绝对路径/image-viewer-mcp/src/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-你的key"
      }
    }
  }
}

配置完成后，直接让 Claude 描述一张图片即可，例如：

帮我看看 /home/user/screenshots/bug.png 里有什么，这是报错截图

手动测试

# 运行单元测试（提示词生成、解析、配置校验）
npm test

# 列出工具
node test/client.js --list

# 识别本地图片（可附加背景信息）
node test/client.js /path/to/image.png "这是监控截图"

# 识别网络图片
node test/client.js "https://example.com/image.jpg"

# 指定返回格式
node test/client.js /path/to/image.png --format json

# 强制重新识别（不使用缓存）
node test/client.js /path/to/image.png --no-cache

# 使用 config.yaml 配置后直接运行服务器（stdio 模式）
npm start

# 指定其他位置的配置文件
node src/index.js --config /path/to/config.yaml

输出示例

analyze_image 调用成功时返回：

{
  "content": [
    { "type": "text", "text": "【简要】...\n\n【详细】...\n\n【总结】..." }
  ],
  "structuredContent": {
    "brief": "简要描述",
    "description": "详细描述",
    "summary": "总结"
  },
  "_meta": { "cache": "hit" }
}

• content 通道按 format 显示：text（默认）为可读文本，json 为 JSON 字符串，raw 为 VLM 原始输出

• structuredContent 始终是结构化的三段字段，供程序化消费

• _meta.cache 表示本次结果来源：hit 命中缓存、miss 新识别并写入缓存、disabled 未启用缓存

失败时（文件不存在、格式不支持、网络错误、API 报错等）返回 isError: true 和中文错误说明，调用方 LLM 可以直接看到原因。

缓存机制

缓存键由三部分构成，各部分在 cache.key_components 中独立开关。参与计算的组件任一变化都会得到不同的缓存，避免返回过期结果：

• image：图片内容 hash（同一张图无论来自路径还是 URL 都相同）

• config：模型与提示词配置 hash（改配置后缓存自动失效）

• context：背景信息 hash（不同背景要求不同的识别结果）

例如背景信息可能频繁变化、又希望同一张图复用缓存时，可以关闭 context 组件：

cache:
  key_components:
    context: false

关闭后，同一张图无论背景怎么变都命中同一缓存。至少需要启用一个组件，全部关闭会在启动时报错。

缓存默认写入项目根目录的 .cache/（已被 .gitignore 忽略），每张图一条 JSON 文件。每条缓存保存完整的模型与提示词参数（model / max_tokens / temperature / top_p / prompts 等）以及命中所用的键组成，便于排查缓存为何命中或失效。缓存读失败或写失败都不影响主流程。

限制

• 图片最大 20MB，与 OpenAI 视觉接口的上限一致

• 模型的识别质量取决于所配置的 VLM，更换更强或更弱的模型会影响输出精度

• 图片数据以 base64 内联形式发送给配置的模型服务商，请勿在需要保密的场景上传敏感图片