内容
# Visor MCP
[](https://github.com/ameshkov/visor-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/visor-mcp)
[](https://github.com/ameshkov/visor-mcp/releases)
> 视觉能力MCP服务器，通过任何兼容OpenAI的聊天完成提供商，为纯文本模型添加视觉能力。
<p align="center">
<img src="docs/assets/visor-mcp.png" alt="Visor MCP illustration" width="600">
</p>
## 目录
- [问题](#问题)
- [解决方案](#解决方案)
- [快速开始](#快速开始)
- [工具](#工具)
- [许可证和归属](#许可证和归属)
---
## 问题
纯文本语言模型无法看到或分析图像。当您与纯文本模型共享用户界面截图、错误对话框、图表或图表时，它无法提取视觉信息。您无法提出诸如“这个错误是什么意思？”，“将此设计转换为代码”，或“您在图表中看到什么趋势？”之类的问题。
## 解决方案
Visor MCP是一个MCP服务器，它弥合了这一差距。它接受来自您的编码代理的图像 - 数据URL、本地文件路径或远程HTTP URL - 并将其转发到兼容OpenAI的视觉提供商。提供商分析图像并返回文本响应，该响应流回您的代理。
您无需具有原生视觉支持的模型即可进行视觉分析。服务器处理图像加载、格式验证、大小限制、重试、超时和取消 - 您的代理只需调用工具并接收结果。
以下是其基本功能的演示。根据任务，模型可以使用除图像描述之外的其他工具：诊断错误截图、创建代码工件、比较两个图像等！
<img src="docs/assets/visor-mcp-demo.png" alt="Visor MCP illustration working" width="600">
> ![重要]
> 请注意，纯文本模型无法看到在您的编码代理的聊天中附加的图像。您必须在提示中指定图像文件的路径（本地或远程）。
## 快速开始
添加服务器时请传递凭证。服务器将在首次使用时通过 `npx` 下载。
MCP服务器至少需要设置以下三个环境变量：
- `VISOR_MCP_BASE_URL` - 您选择的提供商的聊天完成API的基本URL。例如，对于OpenRouter，它将是 `https://openrouter.ai/api/v1`。
- `VISOR_MCP_API_KEY` - 提供商的API密钥。
- `VISOR_MCP_MODEL` - 用于视觉分析的模型。分析图像通常不是经常性任务，因此您可以使用相对昂贵的模型，如Sonnet/Opus或GPT Sol/Terra。
参见 [配置](docs/configuration.md) 以获取所有设置，包括可选环境变量和JSON配置示例。
### MCP压缩路由器
[MCP压缩路由器](https://github.com/ameshkov/mcp-compress-router) 将所有MCP服务器压缩到单个路由器中，仅需两个工具（`get_tool_schema` 和 `invoke_tool`），可节省高达99%的令牌开销。它充当代理：代替每个服务器的完整工具目录被发送到LLM的每个请求，路由器公开一个紧凑的列表，模型按需获取模式。
将Visor MCP注册为下游服务器：
```bash
npx mcp-compress-router add visor-mcp \
--description "用于截图、图表和UI的视觉分析工具。如果您不原生理解图像，请使用它。" \
-e VISOR_MCP_API_KEY=sk-or-v1-your-key-here \
-e VISOR_MCP_BASE_URL=https://openrouter.ai/api/v1 \
-e VISOR_MCP_MODEL=claude-sonnet-5 \
-- npx -y visor-mcp
```
### OpenCode
**opencode:** 添加到您的 `opencode.json` 配置文件中。参见 [opencode MCP服务器文档](https://opencode.ai/docs/mcp-servers/)。
```jsonc
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"visor-mcp": {
"type": "local",
"command": ["npx", "-y", "visor-mcp"],
"environment": {
"VISOR_MCP_API_KEY": "sk-or-v1-your-key-here",
"VISOR_MCP_BASE_URL": "https://openrouter.ai/api/v1",
"VISOR_MCP_MODEL": "claude-sonnet-5"
}
}
}
}
```
### Claude Code
**Claude Code:** 参见 [Claude Code MCP文档](https://code.claude.com/docs/en/mcp)。
```bash
claude mcp add visor-mcp \
--env VISOR_MCP_API_KEY=sk-or-v1-your-key-here \
--env VISOR_MCP_BASE_URL=https://openrouter.ai/api/v1 \
--env VISOR_MCP_MODEL=claude-sonnet-5 \
--transport stdio \
-- npx -y visor-mcp
```
### Codex
**Codex:** 参见 [Codex MCP文档](https://developers.openai.com/codex/mcp)。
```bash
codex mcp add visor-mcp \
--env VISOR_MCP_API_KEY=sk-or-v1-your-key-here \
--env VISOR_MCP_BASE_URL=https://openrouter.ai/api/v1 \
--env VISOR_MCP_MODEL=claude-sonnet-5 \
-- npx -y visor-mcp
```
### Copilot
**GitHub Copilot（VS Code）：** 添加到您的 `.vscode/mcp.json` 文件中，或添加到您的用户级MCP设置中（命令面板 → `MCP：打开用户配置`）。参见 [VS Code MCP文档](https://code.visualstudio.com/docs/agent-customization/mcp-servers)。
```json
{
"servers": {
"visor-mcp": {
"command": "npx",
"args": ["-y", "visor-mcp"],
"env": {
"VISOR_MCP_API_KEY": "sk-or-v1-your-key-here",
"VISOR_MCP_BASE_URL": "https://openrouter.ai/api/v1",
"VISOR_MCP_MODEL": "claude-sonnet-5"
}
}
}
}
```
## 工具
服务器暴露了七种工具。有关详细参考 - 包括参数描述、输出类型、接受的图像源和支持的格式 - 请参见 [工具文档](docs/tools.md)。
| 工具 | 目的 | 字段 |
| --- | --- | --- |
| `ui_diff_check` | 比较预期的UI截图与实际实现以查找视觉差异。 | `expected_image_source`, `actual_image_source`, `prompt` |
| `ui_to_artifact` | 将UI截图转换为前端代码、AI重建提示、设计规范或自然语言描述。 | `image_source`, `output_type`（`code`, `prompt`, `spec`, `description`之一）, `prompt` |
| `extract_text_from_screenshot` | 从源代码截图、终端输出、配置或散文转录文本。 | `image_source`, `prompt`, `programming_language`（可选） |
| `diagnose_error_screenshot` | 分析包含错误、异常或堆栈跟踪的截图以进行诊断。 | `image_source`, `prompt`, `context`（可选） |
| `understand_technical_diagram` | 解释架构图、流程图、UML、实体-关系和序列图。 | `image_source`, `prompt`, `diagram_type`（可选） |
| `analyze_image` | 通用图像分析；未被专用工具覆盖的请求的备用。 | `image_source`, `prompt` |
| `analyze_data_visualization` | 分析图表、图形和仪表板以获取指标、模式和见解。 | `image_source`, `prompt`, `analysis_focus`（可选） |
## 许可证和归属
MIT。行为兼容性源自 `@z_ai/mcp-server`（Apache-2.0），但不意味着Z.AI的认可。
---
## 文档
- [配置](docs/configuration.md) — 环境变量、JSON配置、全局安装、从源代码构建
- [工具](docs/tools.md) — 详细参考，包括图像源和格式规则
- [开发](DEVELOPMENT.md) — 如何设置和贡献
- [LLM代理规则](AGENTS.md) — AI辅助开发指南
- [变更日志](CHANGELOG.md) — 版本历史
