Vision Relay

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.

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

Aspect	v0.1.0	v1.1.0
Tools	2	1
Images per call	1 or exactly 2	1 or more
Request strategy	Task-specific	Prompt-driven
Multi-image handling	Limited to comparison	Any prompt-defined task
File reading	Sequential	Concurrent
Size limit	None	Optional
API formats	Anthropic	Anthropic and OpenAI
Setup docs	Basic	Step-by-step bilingual guides

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.

Name	Required	Default	Description
VISION_PROVIDER	No	anthropic	anthropic or openai
VISION_API_KEY	Yes	none	API key
VISION_BASE_URL	Yes	none	Base URL for the API
VISION_MODEL	Yes	none	Vision-capable model name
VISION_MAX_TOKENS	No	2000	Max response tokens
VISION_MAX_IMAGE_SIZE	No	0	Per-image byte limit

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.

Provider	Base URL you set	Added path
anthropic	host or /v1	/v1/messages
openai	host or /v1	/v1/chat/completions

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."
}

Field	Required	Type	Description
image_paths	Yes	string[]	Absolute image paths
prompt	No	string	Task instruction

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

Extension	MIME type
.png	image/png
.jpg / .jpeg	image/jpeg
.webp	image/webp
.gif	image/gif
.bmp	image/bmp

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.

v0.1.0	v1.1.0
analyze_image + image_path	process_images + image_paths
compare_images + two paths	process_images + paths + prompt

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

Symptom	Likely cause	Check
Not listed	Config path issue	Check args and restart Claude Code
Disconnected	Startup crash	Run node index.js manually
Missing env vars	Config incomplete	Check key, base URL, and model
API 401 or 403	Auth failed	Check API key and provider
API 404	Wrong URL or model	Check base URL and model name
Format error	Provider mismatch	Switch VISION_PROVIDER
Unsupported extension	Bad image format	Use png, jpg, webp, gif, or bmp
File not found	Path error	Use absolute image paths
Image too large	Size limit	Raise limit or compress the image

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 步：准备配置项

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

名称	必填	默认值	说明
VISION_PROVIDER	否	anthropic	anthropic 或 openai
VISION_API_KEY	是	无	API key
VISION_BASE_URL	是	无	接口基础地址
VISION_MODEL	是	无	支持图片输入的模型名
VISION_MAX_TOKENS	否	2000	最大返回 token
VISION_MAX_IMAGE_SIZE	否	0	单图大小上限

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。

旧版和新版对应关系：

v0.1.0	v1.1.0
analyze_image + 单张路径	process_images + image_paths
compare_images + 两张路径	process_images + 两张路径 + 提示词

常见问题

现象	常见原因	处理
服务不显示	配置没加载	检查 .claude.json 并重启
Disconnected	启动失败	手动运行 node index.js
缺少环境变量	env 不完整	检查 key、base URL、model
API 401/403	认证失败	检查 API key
API 404	地址或模型错误	检查 base URL 和模型名
格式错误	provider 不匹配	切换 VISION_PROVIDER
找不到文件	图片路径错误	使用绝对路径
图片过大	超过大小限制	压缩图片或提高限制

安全说明

• 不要把真实 API key 写进代码、README、截图或聊天记录。
• 项目只会访问你配置的 VISION_BASE_URL。
• 如果 key 泄露，应立即轮换。

一句话总结

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