mcp-vision-server
mcp-vision-server
一个适用于所有 OpenAI 兼容视觉模型的 MCP 服务器。
配置一次,即可在 OpenAI、OpenRouter、Zhipu、Bailian、SiliconFlow 等兼容提供商中使用同一个 analyze_image 工具。它适用于 Claude Code、Codex、Cursor、Zed 以及任何其他 MCP 客户端。
为什么使用 mcp-vision-server?
✅ 适用于任何 MCP 客户端 – Claude Code、Codex、Cursor、Zed 等。
✅ 支持众多提供商 – 切换提供商时无需更改提示或工具调用。
✅ 统一 API – 一个工具(
analyze_image)即可用于所有 OpenAI 兼容视觉端点。✅ 灵活的图片输入 – 自动识别 URL、本地文件或 Base64。
✅ 随处覆盖 – 可通过环境变量进行全局配置,或按请求单独配置。
Related MCP server: vision-mcp
快速开始
安装服务器。
设置你的提供商和 API 密钥。
将 MCP 服务器添加到你的客户端。
提问:
Describe this screenshot.如果一切配置正确,你的 MCP 客户端将自动调用 analyze_image 并返回视觉模型的响应。
功能特性
单个
analyze_image工具,接口一致。支持 URL、本地文件和 Base64 图片输入。
内置 13 个提供商预设。
通过
VISION_PROVIDER或provider参数选择提供商。支持环境级别和请求级别的配置覆盖。
示例
让你的 MCP 客户端分析一张图片:
Analyze this screenshot and tell me what UI is shown.客户端调用 MCP 工具:
{
"tool": "analyze_image",
"arguments": {
"image": "/path/to/screenshot.png",
"prompt": "Analyze this screenshot and tell me what UI is shown."
}
}服务器对图片输入进行标准化,将其发送到所选 OpenAI 兼容视觉提供商,并将纯文本答案返回给你的 MCP 客户端。
提供商
内置预设让常见的 OpenAI 兼容视觉端点易于使用:
提供商 | 预设 |
Zhipu |
|
Bailian / DashScope |
|
OpenAI |
|
SiliconFlow |
|
OpenRouter |
|
Ark / Volcengine |
|
StepFun |
|
Kimi / Moonshot |
|
MiniMax |
|
ModelScope |
|
NVIDIA NIM |
|
Novita AI |
|
你也可以通过手动设置 VISION_BASE_URL、VISION_API_KEY 和 VISION_MODEL 来使用任何其他 OpenAI 兼容视觉端点。
安装与运行
需要 Python ≥ 3.10 和 uv。
cd mcp-vision-server
uv sync # install deps
uv run pytest -v # run tests
uv run ruff check . # lint
uv run mcp-vision-server # start stdio server配置
选项 1:提供商预设(推荐)
export VISION_PROVIDER=zhipu # default
export VISION_API_KEY=your_key完整预设列表请参阅 提供商。
你也可以使用提供商特定的环境变量(例如 DASHSCOPE_API_KEY、OPENAI_API_KEY)作为回退。
选项 2:手动配置
变量 | 必填 | 描述 |
| 是 | API 密钥 |
| 否 | OpenAI 兼容端点 |
| 否 | 模型名称 |
工具参数(每次调用覆盖环境变量):image、prompt、image_type、provider、base_url、api_key、model、temperature、max_tokens。
MCP 客户端设置
Claude Code (.mcp.json)
{
"mcpServers": {
"vision": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-vision-server", "mcp-vision-server"],
"env": {
"VISION_PROVIDER": "zhipu",
"VISION_API_KEY": "your_key"
}
}
}
}Claude Code 插件
# After PyPI publish
claude plugins install RuyimgByCN/mcp-vision-server
# Local test
claude plugins install /path/to/mcp-vision-server该仓库包含一个 .claude-plugin.json 清单文件——claude plugins install 会自动读取它。
Codex (OpenAI Codex CLI)
编辑 ~/.codex/config.toml:
[mcp_servers.vision]
command = "uvx"
args = ["mcp-vision-server"]
env = { VISION_PROVIDER = "zhipu", VISION_API_KEY = "your_key" }或者用于本地开发:
[mcp_servers.vision]
command = "uv"
args = ["run", "--directory", "/path/to/mcp-vision-server", "mcp-vision-server"]
env = { VISION_PROVIDER = "zhipu", VISION_API_KEY = "your_key" }Cursor / 其他 uvx 客户端
将 command 替换为 uvx,将 args 替换为 ["--from", "/path/to/mcp-vision-server", "mcp-vision-server"],env 保持不变。
提供商示例
// Bailian
"env": { "VISION_PROVIDER": "bailian", "VISION_API_KEY": "your_key" }
// OpenAI
"env": { "VISION_PROVIDER": "openai", "VISION_API_KEY": "sk-xxx" }
// Fully custom
"env": {
"VISION_BASE_URL": "https://your-endpoint/v1",
"VISION_API_KEY": "your_key",
"VISION_MODEL": "your-model"
}架构
MCP Client (Claude Code / Codex / Cursor / Zed)
│
▼
mcp-vision-server
│
├── mcp_vision_server/server.py # MCP tool entrypoints
├── mcp_vision_server/config.py # env/provider/parameter resolution
├── mcp_vision_server/image.py # URL/file/base64 normalization
└── mcp_vision_server/providers.py # provider presets
│
▼
OpenAI-compatible Vision API
│
▼
Vision model response常见问题
为什么不直接调用视觉提供商?
该服务器为 MCP 客户端提供了一个可复用的统一视觉工具。你可以在不更改客户端提示、MCP 工具名称或客户端集成代码的情况下切换提供商。
我能否使用未列出的提供商?
可以。对于任何 OpenAI 兼容视觉端点,使用 VISION_BASE_URL、VISION_API_KEY 和 VISION_MODEL 进行手动配置即可。
我能否按请求覆盖提供商?
可以。使用 provider、base_url、api_key 或 model 工具参数,可在单次调用中覆盖环境级别的配置。
支持哪些图片格式?
服务器接受图片 URL、本地文件路径和 Base64 字符串。输入类型可以自动检测,也可以通过 image_type 指定。
开发
uv sync --all-groups
uv run ruff check .
uv run ruff format .
uv run pytest -v
uv build
uv run twine check dist/*发布清单
更新
pyproject.toml中的版本号。运行
uv run ruff check .、uv run pytest -v、uv build和uv run twine check dist/*。创建并推送版本标签,例如
v0.1.2。让 GitHub Actions 通过可信发布将包发布到 PyPI。
路线图
当稳定的 OpenAI 兼容视觉端点可用时,添加更多提供商预设。
为 Claude Code、Codex、Cursor 和其他 MCP 客户端添加更丰富的示例。
如果 MCP 客户端用户体验能从中受益,添加可选的流式响应支持。
仅在提供商需要自定义请求逻辑时,将提供商特定行为拆分为插件。
关于
作者: RuyimgByCN
许可证: 仅限个人使用。禁止商用——详见 LICENSE。商业授权请联系作者。
Available Tools
2 toolsanalyze_imageB
Analyze or understand an image.
Use this tool when an MCP client needs image understanding, screenshot analysis, OCR-like text recognition, visual Q&A, or UI restoration.
Inputs: image (required), model, prompt, api_key, +5 more. Returns: result
list_providersA
List all supported provider presets as a JSON array.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have entirely distinct purposes: analyze_image for image understanding and list_providers for listing provider presets. No overlap or ambiguity.
Both tools follow a consistent verb_noun pattern (analyze_image, list_providers), making naming predictable and clear.
Only two tools for a vision server feels slightly thin. While the count is not extreme, it borders on insufficient for typical vision tasks.
The server covers only basic image analysis and a provider listing, missing common vision operations like generation, manipulation, or filtering. The tool surface is significantly incomplete.
Maintenance
Related MCP Connectors
Chat, image, video, and audio models from many vendors behind one remote MCP server and one key.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Related MCP Servers
- FlicenseBqualityDmaintenanceOpenAI-compatible MCP server for running image analysis tools against your own vision model endpoint.76 npm-
- AlicenseAqualityDmaintenanceMCP server that provides an analyze_image tool using OpenAI-compatible vision LLMs to describe images from file paths, URLs, or base64 data.115 npm1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for analyzing images using multiple vision LLM providers (OpenCode, OpenAI, Anthropic, Google, and custom OpenAI-compatible endpoints). Provides tools to analyze single or multiple images, list providers, and test vision capabilities.MIT
- AlicenseAqualityAmaintenanceMCP server that provides vision understanding to non-multimodal agents via 4 tools (analyze/describe/OCR image, list providers), supporting 13 vision providers with automatic fallback and secure URL handling.4281 npmMIT