A
licenseA
qualityD
maintenanceEnables image analysis and understanding using Vision Language Models through OpenAI-compatible APIs. Supports analyzing images from URLs or local files with custom prompts.
1
2
MIT
vision_mcp
by rongtianjie
Provides image understanding capabilities by forwarding images to a locally hosted Ollama vision model via its OpenAI-compatible API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vision_mcpWhat error is shown in this screenshot?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Vision MCP Server
为缺少多模态能力的 LLM（如 DeepSeek）提供图片理解能力。通过 OpenAI-compatible API 将图片转发至视觉模型，以 MCP 工具形式暴露 describe_image，可接入任意支持 MCP 协议的 AI Agent（Claude Code、Cline、Continue.dev 等）。
特性
多种图片来源：本地路径（绝对/相对）、
http(s)://网络图片 URL、data:URI，无需先下载到本地多图分析：一次传入多张图片进行对比、总结
自动压缩：超过
VISION_MAX_UPLOAD_MB的图片自动缩放/转 JPEG（最长边 2048px），降低上传体积与 API 拒绝率多后端（provider）：可同时配置多个视觉 API，按需切换（工具参数或启动参数）
健壮性：瞬时错误自动重试（尊重
Retry-After头 + 指数退避抖动）、响应结构防御性校验、错误按 HTTP 状态分类给出中文提示诊断工具：
vision_ping支持探测视觉 API 连通性（GET /models）配置友好：所有配置通过项目根目录
.env管理，修改后重启 Agent 即生效，无需重新注册 MCP
Related MCP server: api-vision-mcp
一、安装
方式 A：项目内安装（推荐用于开发调试）
cd /path/to/vision_mcp
uv venv && uv pip install -e .方式 B：全局安装（推荐日常使用，注册命令不依赖工作目录）
uv tool install -e /path/to/vision_mcp安装后 vision-mcp 进入 PATH，可在任意目录直接运行（此方式注册最省心）。
二、配置
所有后端配置通过项目根目录 .env 文件管理，无需在 MCP 注册时反复传入环境变量。修改配置后重启 Agent 即可生效。
cp .env.example .env.env 文件内容：
VISION_API_BASE=https://api.siliconflow.cn/v1
VISION_API_KEY=sk-your-key-here
VISION_MODEL=Qwen/Qwen2.5-VL-72B-Instruct
VISION_MAX_TOKENS=2000配置变量总表
变量 | 必填 | 默认值 | 说明 |
| 是 |
| API 地址，不含 |
| 按需 |
| API 密钥（本地部署留空即可） |
| 是 |
| 视觉模型名称 |
| 否 |
| 单次响应最大 token 数（可被工具参数覆盖） |
| 否 |
| API 请求超时（秒） |
| 否 |
| 瞬时错误（429/5xx/超时）最大重试次数 |
| 否 |
| 单张图片最大体积（MB），超过拒绝 |
| 否 |
| 超过该体积的图片自动压缩后再上传 |
| 否 |
| 默认使用的 provider 名称 |
非法配置值（如
VISION_MAX_TOKENS=abc）不会导致启动失败，会告警并回退默认值。启动日志会打印配置摘要（不含 API Key），并提示未找到.env的情况。
多后端（provider）配置
适合同时连接「公网 + 本地」多个视觉服务。命名 provider 的环境变量格式：
VISION_PROVIDER_<NAME>_API_BASE=...
VISION_PROVIDER_<NAME>_API_KEY=...
VISION_PROVIDER_<NAME>_MODEL=...示例（.env 中）：
# 默认 provider（公网）
VISION_API_BASE=https://api.siliconflow.cn/v1
VISION_API_KEY=sk-xxx
VISION_MODEL=Qwen/Qwen2.5-VL-72B-Instruct
# 命名 provider：local
VISION_PROVIDER_LOCAL_API_BASE=http://localhost:11434/v1
VISION_PROVIDER_LOCAL_API_KEY=not-needed
VISION_PROVIDER_LOCAL_MODEL=llava:13b
VISION_PROVIDER=default # 默认使用哪个切换后端有三种方式（优先级从高到低）：
调用工具时传
provider参数（如provider="local"），仅本次生效启动时
vision-mcp --provider local，本次会话生效修改
VISION_PROVIDER环境变量，重启 Agent 生效
启动参数
vision-mcp [--env-file PATH] [--provider NAME] [--version]
--env-file PATH 从指定 .env 文件加载配置（优先级最高，可替代自动发现的 .env）
--provider NAME 默认使用的 provider 名称
.env查找顺序：当前工作目录 → 项目根目录。若你的 Agent 不在项目根目录启动（如 Claude Code 的 user 级注册），请用--env-file /path/to/vision_mcp/.env显式指定。
三、注册到 AI Agent
方式 A：使用项目内 .mcp.json（Cline、Continue.dev 等）
项目已内置 .mcp.json，支持此格式的 Agent 会自动识别：
{
"mcpServers": {
"vision": {
"command": "uv",
"args": ["run", "vision-mcp"]
}
}
}⚠️ 该写法要求 Agent 以项目根目录为工作目录（Cline/Continue 以项目根打开时满足）。若你的客户端不满足，请改用绝对路径：
{ "mcpServers": { "vision": { "command": "uv", "args": ["run", "--project", "/path/to/vision_mcp", "vision-mcp"] } } }
方式 B：Claude Code 手动注册
推荐（已全局安装）：
claude mcp add-json -s user vision '{
"command": "vision-mcp",
"args": []
}'未全局安装（必须带绝对路径，否则 uv run 找不到包）：
claude mcp add-json -s user vision '{
"command": "uv",
"args": ["run", "--project", "/path/to/vision_mcp", "vision-mcp"]
}'方式 C：uv tool install + 任意注册
按「一、安装」方式 B 全局安装后，任何注册命令都只需 "command": "vision-mcp"，无 cwd 依赖。
所有方式均无需携带
env字段，配置已由.env文件管理。
四、验证
vision-mcp --version # 输出版本号
vision-mcp --help # 查看启动参数确认 Agent 中 MCP Server 状态为已连接（Claude Code: claude mcp list → vision: vision-mcp - ✓ Connected）。连接后调用 vision_ping（probe_api: true 可同时检查视觉 API 连通性）。
五、工作原理
User: "看看这张截图"
→ AI Agent (DeepSeek, 无视觉)
→ 调用 describe_image 工具
→ Vision MCP Server: 读取本地图片 / 下载 URL → Base64 → POST 视觉模型 API
← 返回文字描述
→ AI Agent 基于描述回答用户六、工具说明
describe_image — 理解图片内容
参数 | 必填 | 类型 | 说明 |
| 否* |
| 本地图片路径（绝对或相对，相对基于 Agent 启动目录），兼容旧版单图用法 |
| 否* |
| 网络图片 URL（http/https），自动下载 |
| 否* |
| 多张图片（路径/URL 混合），用于对比或总结 |
| 否 |
| 描述侧重，如 "提取所有文字"、"描述图表趋势" |
| 否 |
| 覆盖环境变量 |
| 否 |
| 指定后端（需在 |
* 三个图片来源参数至少提供一个；同时提供时自动合并。也支持 data: URI。
支持格式：PNG / JPG / JPEG / JFIF / GIF / WebP / BMP / HEIC / AVIF / TIFF
单文件限制：≤
VISION_MAX_IMAGE_MB（默认 20 MB）自动压缩：超过
VISION_MAX_UPLOAD_MB（默认 8 MB）的图片自动缩放/转 JPEG 后上传多图：多张图按顺序放入一次请求（OpenAI-compatible 多模态格式）
vision_ping — 诊断连通性
参数 | 必填 | 类型 | 说明 |
| 否 |
| 任意测试字符串，原样回显 |
| 否 |
| 是否额外请求 |
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call",\
"params":{"name":"vision_ping","arguments":{"msg":"hello"}}}' | vision-mcp七、使用示例
User: 看看 @error_screenshot.png 里的报错信息
User: 分析 @architecture.png 的系统设计有什么问题
User: 把 @data_table.png 转成 markdown 表格
User: @chart.png 描述数据变化趋势，控制在 200 字以内
User: 对比 @before.png 和 @after.png 的界面差异 # 多图
User: 分析 https://example.com/chart.png 的数据趋势 # 网络图片八、更新配置
修改 .env 文件后重启 AI Agent 即可生效，无需重新注册 MCP。
如需更换 Provider 的 API 地址，可参考以下配置：
Provider |
| 推荐 |
SiliconFlow |
|
|
本地 vLLM |
|
|
本地 Ollama |
|
|
One-API 网关 |
|
|
常见问题
Failed to connect？
确认
vision-mcp --version可执行检查 API 连通性：
curl $VISION_API_BASE/models运行
vision-mcp查看 stderr 日志（启动时会打印配置摘要与.env加载情况）Agent 内调用
vision_ping，probe_api: true一键排查
注册后连不上，日志显示找不到 vision-mcp？
uv run vision-mcp 依赖工作目录。请改用绝对路径：uv run --project /path/to/vision_mcp vision-mcp，或按「方式 C」全局安装后直接注册 vision-mcp。
返回乱码或空内容？
尝试将图片转为 PNG 格式
缩小图片尺寸（Base64 后体积增大约 33%）
更换更强大的视觉模型
图片数据会留存吗？
不会。图片仅通过 Base64 编码后 HTTPS 发送至视觉 API，Server 不做本地存储或缓存。使用公网 API 时注意勿传入敏感图片。
如何临时切换视觉服务？
调用工具时传 provider 参数（需先在 .env 配置好命名 provider），或在启动命令加 --provider <名称>。
HEIC 图片无法识别？
扩展名识别支持 HEIC，但上传前压缩需要 pillow-heif；未安装时会原样上传，由视觉 API 决定是否支持。
Available Tools
2 toolsdescribe_imageA
理解并描述图片内容。传入本地图片文件绝对路径，返回对该图片的详细文字描述。当用户让你查看、理解、分析或描述任何图片时，你必须调用此工具。支持 PNG、JPG、JPEG、GIF、WebP、BMP 等常见图片格式。
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | ||
| image_path | Yes | ||
| max_tokens | No |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that it returns a text description and supports common image formats, but it does not mention potential failure modes, side-effect-free nature, or behavior with invalid paths. For a simple read-only tool this is adequate but not rich.
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?
The description is concise, with three sentences covering purpose, requirement, usage trigger, and supported formats. No redundant information; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality, input requirement, formats, and when to use. With an output schema present, return value details are handled. However, optional parameters (prompt, max_tokens) are not explained, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains that image_path must be an absolute local path and enumerates supported formats, but it fails to explain the `prompt` and `max_tokens` parameters, leaving their semantics unclear despite their names being suggestive.
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?
The description explicitly states the tool understands and describes image content, returns detailed text, and specifies when to call it (when user asks to view/understand/analyze/describe any image). This clearly distinguishes it from the sibling tool vision_ping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to use this tool whenever the user asks to view, understand, analyze, or describe any image, and specifies that the input must be an absolute local file path. This provides clear usage context, though it doesn't mention exclusions for non-local or URL-based images.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
vision_pingA
Diagnostic: return a test string to verify MCP communication.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| msg | No | ping |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states the tool returns a test string, and the word 'Diagnostic' implies a non-destructive, read-only operation. However, it does not explicitly confirm side-effect-free behavior or mention any limitations, which is minimal for a tool with zero annotation coverage.
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?
The description is a single, front-loaded sentence: 'Diagnostic: return a test string to verify MCP communication.' It is concise and every word serves a purpose, with no 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?
For a simple ping tool, the description covers the core purpose and return value. An output schema exists, so return details are not needed. However, the mismatch between the parameter 'msg' and the description (which never mentions it) makes the tool incomplete for correct custom invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema defines one optional parameter 'msg' with a default 'ping', but schema description coverage is 0%. The description does not mention this parameter at all, so agents have no way to know they can customize the returned string. This is a significant gap for a single-parameter tool.
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?
The description clearly identifies the tool as a diagnostic action: 'return a test string to verify MCP communication.' The verb 'return' and resource 'test string' are specific, and the 'Diagnostic' prefix distinguishes it from sibling describe_image, which handles image content.
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?
The phrase 'to verify MCP communication' provides clear usage context. The 'Diagnostic' label implies it is for testing connectivity, not for normal image analysis. It does not explicitly exclude other use cases, but the context is sufficient for a ping tool.
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.
2 tool updates
v1.1.0- First observed
describe_image - First observed
vision_ping
TDQS
A3.7/5.0
Scored across 2 tools
Disambiguation5/5
The two tools serve completely distinct purposes: vision_ping is a diagnostic health-check, while describe_image is the core functionality. There is no overlap, and an agent can easily tell which tool to use based on the user's intent.
Naming Consistency3/5
vision_ping follows a noun-verb pattern with a prefix, while describe_image uses a verb-noun pattern. Both names are clear and readable, but the inconsistent structure makes the set less predictable than a uniform convention.
Tool Count3/5
With only two tools, the server feels thin for a vision MCP. One diagnostic and one core tool is borderline, but it could be acceptable for a minimal, focused server. It lacks the breadth expected from a more complete toolset.
Completeness3/5
The server covers only image description, with no additional vision capabilities like OCR, object detection, or metadata extraction. For a dedicated vision server, this is a notable gap, but the core describe functionality is present and usable.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Generate images with your own ChatGPT subscription (Plus, Pro or Team), without spending API credits
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Turn any LLM multimodal; generate images, voices, videos, 3D models, music, and more.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables image recognition using vision models via OpenAI-compatible APIs, supporting multiple platforms like OpenAI, DeepSeek, and Ollama.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to analyze images using any OpenAI-compatible vision API, providing tools for image analysis, OCR, error diagnosis, diagram understanding, and chart analysis.MIT
- FlicenseNot gradedqualityBmaintenanceEnables pure text LLMs to understand images by acting as a proxy to vision models via OpenAI-compatible APIs. Supports local files, URLs, and base64 inputs for image analysis.-