weekitmo/vision-mcp

Vision MCP

通过任何兼容 OpenAI 的提供商为纯文本代理赋予视觉能力。

安装 ·
配置 ·
MCP 客户端 ·
Inspector ·
mcporter

使用任何兼容 OpenAI 的视觉模型分析本地图像、网络图像、截图、文档、图表和代码错误。

[!IMPORTANT]
如果你原生支持视觉并且能够直接访问所提供的图像，请勿调用。

当当前模型能够直接检查图像时，请跳过此 MCP。仅当模型缺乏视觉能力、无法访问图像，或用户明确要求使用此 MCP 时才使用它。

安装

首先安装 uv。

直接从 GitHub main 分支运行：

uvx --from git+https://github.com/weekitmo/vision-mcp.git@main vision-mcp

配置

配置以下四个环境变量：

export VISION_BASE_URL="https://api.openai.com/v1"
export VISION_API_KEY="your-api-key"
export VISION_MODEL="your-vision-model"
export VISION_TIMEOUT="120"

| 变量 | 描述 |
| --- | --- |
| VISION_BASE_URL | 兼容 OpenAI 的提供商 URL |
| VISION_API_KEY | API 密钥 |
| VISION_MODEL | 支持图像输入的模型 |
| VISION_TIMEOUT | 请求超时时间（秒）；默认为 120 |

使用 .env.example 作为配置模板。切勿提交真实的 API 密钥。

MCP 客户端

JSON

对于支持标准 JSON MCP 配置格式的客户端：

{
"mcpServers": {
"vision": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/weekitmo/vision-mcp.git@main",
"vision-mcp"
],
"env": {
"VISION_BASE_URL": "https://api.openai.com/v1",
"VISION_API_KEY": "your-api-key",
"VISION_MODEL": "your-vision-model",
"VISION_TIMEOUT": "120"
}
}
}
}

Codex

将以下内容添加到 ~/.codex/config.toml 或受信任项目中的 .codex/config.toml：

[mcp_servers.vision]
command = "uvx"
args = [
"--from",json
"git+https://github.com/weekitmo/vision-mcp.git@main",
"vision-mcp",
]
env_vars = [
"VISION_BASE_URL",
"VISION_API_KEY",
"VISION_MODEL",
"VISION_TIMEOUT",
]
startup_timeout_sec = 60
tool_timeout_sec = 180

env_vars 列表声明了 Codex 应将哪些变量转发给 Vision MCP；
它并不包含这些变量的值。在启动 Codex 之前，请在同一个终端中配置上游视觉服务提供方：
sh
export VISION_BASE_URL="https://api.openai.com/v1"
export VISION_API_KEY="your-api-key"
export VISION_MODEL="your-vision-model"
export VISION_TIMEOUT="120"

这些设置配置的是 Vision MCP 所使用的提供方。它们与 Codex 本身所使用的账户或 API 密钥相互独立。导出这些变量后，启动 Codex 或验证 MCP 服务器是否已注册：
sh
codex mcp list

完整示例请参见 config/codex.toml.example。

DeepSeek Harness

将以下补丁条目添加到
$HOME/.dsh/profiles/web/cordis.patch.yml：
yaml
Your patch layer for this dsh profile, applied after every bundle layer:
a top-level YAML array of loader patch entries (id-targeted config
overrides, disables, and insert lists; !!js expressions allowed).

Vision MCP server (stdio). Exposes tools as mcp__vision__.
Image understanding / OCR via an OpenAI-compatible vision Chat Completions API.
docs: https://github.com/weekitmo/vision-mcp
- insert:
- id: mcp-vision
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: vision
transport: stdio
command: uvx
args:
- '--from'
- 'git+https://github.com/weekitmo/vision-mcp.git@main'
- vision-mcp
env:
VISION_BASE_URL: 'https://api.openai.com/v1'
VISION_API_KEY: !!js process.env.VISION_API_KEY
VISION_MODEL: !!js process.env.VISION_MODEL
VISION_TIMEOUT: '120'

在启动 DeepSeek Harness 之前，请导出 VISION_API_KEY 和 VISION_MODEL。
如果视觉模型由其他兼容 OpenAI 的提供方托管，请更改 VISION_BASE_URL。

Grok

将以下内容添加到 ~/.grok/config.toml 或项目的
.grok/config.toml：
toml
[mcp_servers.vision]
command = "uvx"
args = [
"--from",
"git+https://github.com/weekitmo/vision-mcp.git@main",
"vision-mcp",
]
enabled = true
startup_timeout_sec = 60
tool_timeout_sec = 180

[mcp_servers.vision.env]
VISION_BASE_URL = "https://api.openai.com/v1"
VISION_API_KEY = "your-api-key"
VISION_MODEL = "your-vision-model"
VISION_TIMEOUT = "120"

Grok 不使用 Codex 的 env_vars 列表。它使用
[mcp_servers.vision.env] 直接配置 MCP 进程的环境。
预期的变量名是 VISION_BASE_URL，而不是 VISION_API_BASE_URL。

为避免将 API 密钥直接存储在 TOML 中，请引用 Grok 启动时可用的环境变量：
toml
[mcp_servers.vision.env]
VISION_BASE_URL = "${VISION_BASE_URL}"
VISION_API_KEY = "${VISION_API_KEY}"
VISION_MODEL = "${VISION_MODEL}"
VISION_TIMEOUT = "${VISION_TIMEOUT:-120}"

这些设置用于配置 Vision MCP 所使用的提供商。它们独立于 Grok 本身所使用的账户或 API 密钥。不要提交包含真实 API 密钥的项目级 .grok/config.toml。使用以下命令验证配置：
sh
grok mcp list

完整示例请参见 config/grok.toml.example。

Inspector

使用以下命令启动 MCP Inspector：
sh
./scripts/test-ui.sh

该脚本固定使用 @modelcontextprotocol/inspector@2.1.0。

在 Inspector 中：

1. 打开 vision-local。
2. 在 Environment Variables 下输入四个 VISION_ 设置。
3. 连接到服务器。
4. 打开 Tools。
5. 选择 analyze_image 或 understand_image。
6. 输入图像路径和提示词，然后运行该工具。

Inspector 将其本地配置存储在 .inspector/mcp.json 中，该文件已从 Git 中排除。

mcporter

初始化项目配置：
sh
./scripts/setup-mcporter.sh

查看可用的工具：
sh
mcporter list vision --schema --all-parameters

分析单张图像：
sh
mcporter call vision.analyze_image \
image=/absolute/path/to/screenshot.png \
prompt="Extract all text from this image" \
mode=ocr \
detail=high \
--timeout 120000

比较多张图像：
sh
mcporter call vision.understand_image \
--args '{
"images": [
"/absolute/path/before.png",
"/absolute/path/after.png"
],
"prompt": "Compare the differences between these images",
"mode": "compare"
}' \
--timeout 120000 \
--output json

阅读内置文档资源：
sh
mcporter resource vision
mcporter resource vision vision://docs/quickstart
mcporter resource vision vision://docs/tools

工具

analyze_image

分析单张图像。此工具适用于 Inspector、mcporter 和命令行调用。
text
image       本地路径、HTTP(S) URL 或 data URL
prompt      向模型提出的问题或指令
mode        分析模式
ascii_mode  是否使用 ASCII 表示布局
detail      图像输入细节级别
max_tokens  最大输出长度

understand_image

分析或比较多张图像。此工具还支持使用不同图像参数格式的客户端。
text
images      图像列表
prompt      向模型提出的问题或指令
mode        分析模式
ascii_mode  是否使用 ASCII 表示布局
detail      图像输入细节级别
max_tokens  最大输出长度

可用模式：

auto · describe · ocr · document · ui · chart · compare ·
spatial · code

支持 PNG、JPEG、WEBP 和 GIF。每次调用最多接受 10 张图像。

从源码运行

用于开发或调试：
sh
git clone https://github.com/weekitmo/vision-mcp.git
cd vision-mcp
uv sync --frozen
uv run vision-mcp

在 MCP 客户端中从源码运行：
json
{
"mcpServers": {
"vision": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/vision-mcp",
"run",
"--frozen",
"vision-mcp"
],
"env": {
"VISION_BASE_URL": "https://api.openai.com/v1",
"VISION_API_KEY": "your-api-key",
"VISION_MODEL": "your-vision-model",
"VISION_TIMEOUT": "120"
}
}
}
}

许可证

MIT