Vision Relay MCP

A local MCP server that gives Claude Code image understanding through a vision-capable API. It reads local image files, sends them to your configured vision endpoint, and returns the text response to Claude Code.

This document is bilingual. English is first, Chinese follows.

What It Does

Claude Code cannot view images by itself. Vision Relay MCP bridges local image files and a vision model:

Local image(s) -> Vision Relay MCP -> Vision API -> Text result -> Claude Code

Claude Code calls one tool, process_images. The server handles file reading, validation, base64 encoding, API communication, and response extraction.

The server is a single local Node.js file. It does not store images, cache results, or call any service other than the endpoint you configure.

Related MCP server: Vison-MCP

Version History

v1.1.0 Current

v1.1.0 is a single-entry upgrade. It replaces the old analyze_image and compare_images tools with one prompt-driven tool: process_images.

Upgrade highlights from v0.1.0:

• One reusable entry point. v0.1.0 separated single-image analysis and two-image comparison into two tools. v1.1.0 uses process_images for OCR, comparison, screenshot explanation, information extraction, visual Q&A, and any other image task the connected model can handle.

• Prompt-driven behavior. The task is no longer limited by the tool name. Tell the model what you need in prompt, such as "extract text", "compare these screenshots", or "return structured JSON".

• Flexible image count. v0.1.0 accepted one image for analyze_image or exactly two images for compare_images. v1.1.0 accepts one or more image paths in the same image_paths array.

• One combined model request. Multi-image tasks are sent together so the model can reason across all images in one context.

• Concurrent local file reading. Multiple image files are read with Promise.all() before the API call, reducing local preparation time for multi-image requests.

• Optional image size guard. VISION_MAX_IMAGE_SIZE can reject oversized images before they are sent to the API.

• Broader endpoint compatibility. v0.1.0 used the Anthropic Messages format. v1.1.0 supports both Anthropic-compatible and OpenAI-compatible vision endpoints.

• More portable documentation. The setup guide now covers Claude Code CLI, .claude.json, Windows path escaping, upgrade steps, and privacy guidance.

v0.1.0 First Version

v0.1.0 exposed two task-specific tools:

• analyze_image for one image

• compare_images for exactly two images

Requirements

• Node.js 18.0.0 or newer

• Claude Code or another MCP-compatible client

• A vision-capable API endpoint

• An API key for that endpoint

The model set in VISION_MODEL must support image input. A text-only model can connect successfully, but it will fail when an image is sent.

Step 1: Install the Project

Clone or download the project, then install dependencies:

git clone https://github.com/zhoucoolboy/vision-relay-mcp.git
cd vision-relay-mcp
npm install
npm run check

npm run check runs node --check index.js. It validates syntax without starting the MCP server or making network requests.

There is no build step.

Step 2: Prepare Configuration Values

All runtime settings are read from environment variables.

VISION_API_KEY takes priority. If it is not set, the server also checks ANTHROPIC_API_KEY and OPENAI_API_KEY.

URL Handling

The server completes provider-specific paths for you.

If VISION_BASE_URL already ends with the full request path, it is used as-is.

Step 3: Add the MCP Server to Claude Code

The easiest and most portable setup is the Claude Code CLI.

Option A: Claude Code CLI

Run this from the project directory. Replace every placeholder value first.

claude mcp add -s user vision-relay \
  -e VISION_PROVIDER=anthropic \
  -e VISION_BASE_URL=https://your-relay.example.com \
  -e VISION_MODEL=your-vision-model \
  -e VISION_API_KEY=your_api_key_here \
  -- node /absolute/path/to/vision-relay-mcp/index.js

For an OpenAI-compatible endpoint, use:

claude mcp add -s user vision-relay \
  -e VISION_PROVIDER=openai \
  -e VISION_BASE_URL=https://your-openai-compatible-endpoint.example.com \
  -e VISION_MODEL=your-vision-model \
  -e VISION_API_KEY=your_api_key_here \
  -- node /absolute/path/to/vision-relay-mcp/index.js

Windows users can use a Windows absolute path:

claude mcp add -s user vision-relay `
  -e VISION_PROVIDER=anthropic `
  -e VISION_BASE_URL=https://your-relay.example.com `
  -e VISION_MODEL=your-vision-model `
  -e VISION_API_KEY=your_api_key_here `
  -- node C:\path\to\vision-relay-mcp\index.js

Option B: Edit .claude.json

Claude Code also stores user-level MCP configuration in:

• Windows: %USERPROFILE%\.claude.json

• macOS/Linux: ~/.claude.json

Add a vision-relay entry under mcpServers. Use an absolute path for index.js.

{
  "mcpServers": {
    "vision-relay": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/vision-relay-mcp/index.js"],
      "env": {
        "VISION_PROVIDER": "anthropic",
        "VISION_BASE_URL": "https://your-relay.example.com",
        "VISION_MODEL": "your-vision-model",
        "VISION_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Windows JSON, escape backslashes:

"args": ["C:\\path\\to\\vision-relay-mcp\\index.js"]

Step 4: Restart and Verify Claude Code

After changing MCP configuration, restart Claude Code.

Verify the connection:

claude mcp list

You should see vision-relay ... Connected.

Step 5: Use process_images

Tool Input

Input:

{
  "image_paths": ["/absolute/path/to/image.png"],
  "prompt": "Extract all visible text."
}

If prompt is omitted, the server uses a general image analysis prompt.

Examples

OCR:

{
  "image_paths": ["/absolute/path/to/screenshot.png"],
  "prompt": "Extract all visible text. Preserve reading order."
}

Comparison:

{
  "image_paths": [
    "/absolute/path/to/before.png",
    "/absolute/path/to/after.png"
  ],
  "prompt": "Compare these images and list meaningful differences."
}

Structured extraction:

{
  "image_paths": ["/absolute/path/to/form.jpg"],
  "prompt": "Extract visible fields as a JSON object."
}

Multi-image sequence:

{
  "image_paths": [
    "/absolute/path/to/step-1.png",
    "/absolute/path/to/step-2.png",
    "/absolute/path/to/step-3.png"
  ],
  "prompt": "These are sequential steps. Describe each step."
}

Supported Image Formats

Other formats, such as SVG, PDF, or HEIC, should be converted first.

Upgrade From v0.1.0

Download v1.1.0 to a new directory:

git clone https://github.com/zhoucoolboy/vision-relay-mcp.git vision-relay-mcp-v1.1
cd vision-relay-mcp-v1.1
npm install

Then:

1. Update the MCP args path to the new index.js.

2. Keep your existing endpoint, model, and API key values.

3. Replace old tool usage as shown below.

4. Restart Claude Code.

5. Run claude mcp list.

Security

• Never commit real API keys.

• Keep secrets in the MCP env block or a secret manager.

• The server only calls VISION_BASE_URL.

• The server does not store images, cache results, or write analysis output.

• Rotate a key immediately if it appears in logs, screenshots, or git history.

Troubleshooting

Basic checks:

node --version
node --check index.js
claude mcp list

Project Structure

vision-relay-mcp/
├── index.js
├── package.json
├── package-lock.json
├── README.md
├── README.zh-CN.md
├── LICENSE
├── .env.example
└── .gitignore

License

MIT. See LICENSE.

中文说明

1.1.0 是 v0.1.0 的单入口升级版。

它把旧版的 analyze_image 和 compare_images 合并为一个 process_images 工具。单图、多图、OCR、对比、提取信息等任务都通过同一个入口处理，具体做什么由提示词决定。

相比第一版升级了什么

• 入口更统一。 第一版把单图分析和双图对比分成 analyze_image、compare_images 两个工具。新版只保留 process_images，使用时不用先判断该选哪个工具。

• 任务不再被工具名限制。 第一版的 compare_images 更像专门的图片对比。新版由提示词决定任务，可以做 OCR、截图说明、设计稿对比、表单信息提取、多图流程总结等。

• 图片数量更灵活。 第一版要么一张图，要么刚好两张图。新版的 image_paths 是数组，可以传一张，也可以传多张。

• 多图放在同一次模型请求里。 新版会把多张图片一起交给模型，让模型在同一上下文里理解图片之间的关系。

• 本地读图改为并发。 多张图片会先并发读取和编码，再统一请求接口，多图场景下准备速度更好。

• 增加图片大小保护。 可以通过 VISION_MAX_IMAGE_SIZE 设置单图大小上限，避免过大的图片直接发到接口。

• 接口兼容范围更广。 第一版主要面向 Anthropic Messages 格式。
  新版支持 anthropic 和 openai 两种 provider，
  能接 Anthropic 兼容接口，也能接 OpenAI Chat Completions 兼容接口。

• 文档更适合复现部署。 新版补充了 Claude Code CLI、.claude.json、Windows 路径转义、升级步骤、常见问题和隐私注意事项。

项目简介

Claude Code 不能直接看图片。Vision Relay MCP 是本地图片和视觉模型之间的桥梁：

本地图片 -> Vision Relay MCP -> 视觉模型 API -> 文本结果 -> Claude Code

Claude Code 调用 process_images，服务负责读取图片、校验格式、base64 编码、调用接口并返回文本结果。

服务是本地单文件实现，不存储图片、不缓存结果，也不会调用你配置之外的服务。

运行要求

• Node.js 18.0.0 或更高版本

• Claude Code 或其他 MCP 客户端

• 支持图片输入的视觉模型接口

• 这个接口的 API key

VISION_MODEL 必须是支持图片输入的模型。纯文本模型不能识图。

第 1 步：安装项目

git clone https://github.com/zhoucoolboy/vision-relay-mcp.git
cd vision-relay-mcp
npm install
npm run check

npm run check 只检查语法，不会启动服务，也不会发起网络请求。

第 2 步：准备配置项

所有配置都通过环境变量传入。

API key 回退顺序：

VISION_API_KEY -> ANTHROPIC_API_KEY -> OPENAI_API_KEY

第 3 步：添加 Claude Code MCP 配置

推荐使用 Claude Code CLI：

claude mcp add -s user vision-relay \
  -e VISION_PROVIDER=anthropic \
  -e VISION_BASE_URL=https://your-relay.example.com \
  -e VISION_MODEL=your-vision-model \
  -e VISION_API_KEY=your_api_key_here \
  -- node /absolute/path/to/vision-relay-mcp/index.js

Windows PowerShell 示例：

claude mcp add -s user vision-relay `
  -e VISION_PROVIDER=anthropic `
  -e VISION_BASE_URL=https://your-relay.example.com `
  -e VISION_MODEL=your-vision-model `
  -e VISION_API_KEY=your_api_key_here `
  -- node C:\path\to\vision-relay-mcp\index.js

也可以直接编辑 Claude Code 用户级配置文件：

• Windows: %USERPROFILE%\.claude.json

• macOS/Linux: ~/.claude.json

示例：

{
  "mcpServers": {
    "vision-relay": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/vision-relay-mcp/index.js"],
      "env": {
        "VISION_PROVIDER": "anthropic",
        "VISION_BASE_URL": "https://your-relay.example.com",
        "VISION_MODEL": "your-vision-model",
        "VISION_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windows JSON 路径需要转义反斜杠：

"args": ["C:\\path\\to\\vision-relay-mcp\\index.js"]

第 4 步：重启并验证 Claude Code

保存后重启 Claude Code，再执行：

claude mcp list

看到 vision-relay ... Connected 就说明 MCP 已启动。

第 5 步：开始使用

在 Claude Code 里直接说明图片路径和任务即可。

单图 OCR：

请调用 vision-relay 分析这张截图，并提取所有文字：
C:\path\to\screenshot.png

多图对比：

请调用 vision-relay 对比这两张设计稿：
C:\path\to\before.png
C:\path\to\after.png

结构化提取：

请调用 vision-relay 读取这张表单图片，并整理成 JSON：
C:\path\to\form.jpg

底层工具输入格式：

{
  "image_paths": [
    "/absolute/path/to/image-1.png",
    "/absolute/path/to/image-2.jpg"
  ],
  "prompt": "比较这些图片，并提取可见文字。"
}

如果不传 prompt，工具会使用默认提示词，让模型综合分析图片内容、文字、对象、颜色、布局和多图关系。

从 v0.1.0 升级

1. 下载 v1.1.0 到新目录。

2. 执行 npm install。

3. 把 MCP 配置里的 args 改成新版 index.js 路径。

4. 保留原来的接口地址、模型名和 API key。

5. 重启 Claude Code。

6. 执行 claude mcp list。

旧版和新版对应关系：

常见问题

安全说明

• 不要把真实 API key 写进代码、README、截图或聊天记录。

• 项目只会访问你配置的 VISION_BASE_URL。

• 如果 key 泄露，应立即轮换。

一句话总结

Claude Code 负责对话和写代码
Vision Relay MCP 负责把图片交给视觉模型
视觉模型返回文字结果
Claude Code 继续处理你的任务