MCP OpenVision

概述

MCP OpenVision 是一个模型上下文协议 (MCP) 服务器，提供由 OpenRouter 视觉模型驱动的图像分析功能。它使 AI 助手能够通过 MCP 生态系统中的简单界面进行图像分析。

安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 mcp-openvision：

npx -y @smithery/cli install @Nazruden/mcp-openvision --client claude

使用 pip

pip install mcp-openvision

使用紫外线（推荐）

uv pip install mcp-openvision

配置

MCP OpenVision 需要 OpenRouter API 密钥，可以通过环境变量进行配置：

OPENROUTER_API_KEY （必需）：您的 OpenRouter API 密钥
OPENROUTER_DEFAULT_MODEL （可选）：要使用的视觉模型

OpenRouter 愿景模型

MCP OpenVision 可与任何支持视觉功能的 OpenRouter 型号兼容。默认型号为qwen/qwen2.5-vl-32b-instruct:free ，但您可以指定任何其他兼容型号。

OpenRouter 提供的一些流行视觉模型包括：

qwen/qwen2.5-vl-32b-instruct:free （默认）
anthropic/claude-3-5-sonnet
anthropic/claude-3-opus
anthropic/claude-3-sonnet
openai/gpt-4o

您可以通过设置OPENROUTER_DEFAULT_MODEL环境变量或将model参数直接传递给image_analysis函数来指定自定义模型。

用法

使用 MCP Inspector 进行测试

测试 MCP OpenVision 最简单的方法是使用 MCP Inspector 工具：

npx @modelcontextprotocol/inspector uvx mcp-openvision

与 Claude Desktop 或 Cursor 集成

编辑您的 MCP 配置文件：
- Windows： %USERPROFILE%\.cursor\mcp.json
- macOS： ~/.cursor/mcp.json或~/Library/Application Support/Claude/claude_desktop_config.json
添加以下配置：

{
  "mcpServers": {
    "openvision": {
      "command": "uvx",
      "args": ["mcp-openvision"],
      "env": {
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "OPENROUTER_DEFAULT_MODEL": "anthropic/claude-3-sonnet"
      }
    }
  }
}

本地运行以进行开发

# Set the required API key
export OPENROUTER_API_KEY="your_api_key"

# Run the server module directly
python -m mcp_openvision

特征

MCP OpenVision 提供以下核心工具：

image_analysis ：使用视觉模型分析图像，支持各种参数：
- image ：可以提供为：
  - Base64编码的图像数据
  - 图片网址 (http/https)
  - 本地文件路径
- query ：图像分析任务的用户指令
- system_prompt ：定义模型的角色和行为的指令（可选）
- model ：使用的视觉模型
- temperature ：控制随机性（0.0-1.0）
- max_tokens ：最大响应长度

制定有效的查询

query参数对于从图像分析中获得有用的结果至关重要。精心设计的查询会提供以下方面的上下文：

目的：你为什么要分析这张图片
重点领域：需要注意的具体元素或细节
所需信息：您需要提取的信息类型
格式偏好：您希望结果如何构建

有效查询示例

基本查询	增强查询
“描述一下这张图片”	“识别此商店货架图片中可见的所有零售产品并估算其价格范围”
“这张图片里有什么？”	分析此医学扫描是否存在异常，重点关注突出显示的区域并提供可能的诊断
“分析此图表”	“从显示季度销售额的条形图中提取数值数据，并确定 2022-2023 年的主要趋势”
“阅读文本”	“转录此餐厅菜单中所有可见的文字，保留菜品名称、描述和价格”

通过提供有关为什么需要分析以及您正在寻找的具体信息的背景信息，您可以帮助模型关注相关细节并产生更有价值的见解。

示例用法

# Analyze an image from a URL
result = await image_analysis(
    image="https://example.com/image.jpg",
    query="Describe this image in detail"
)

# Analyze an image from a local file with a focused query
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="Identify all traffic signs in this street scene and explain their meanings for a driver education course"
)

# Analyze with a base64-encoded image and a specific analytical purpose
result = await image_analysis(
    image="SGVsbG8gV29ybGQ=...",  # base64 data
    query="Examine this product packaging design and highlight elements that could be improved for better visibility and brand recognition"
)

# Customize the system prompt for specialized analysis
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="Analyze the composition and artistic techniques used in this painting, focusing on how they create emotional impact",
    system_prompt="You are an expert art historian with deep knowledge of painting techniques and art movements. Focus on formal analysis of composition, color, brushwork, and stylistic elements."
)

图像输入类型

image_analysis工具接受几种类型的图像输入：

Base64 编码字符串
图片 URL - 必须以 http:// 或 https:// 开头
文件路径：
- 绝对路径：以 /（Unix）或驱动器号（Windows）开头的完整路径
- 相对路径：相对于当前工作目录的路径
- 带有 project_root 的相对路径：使用project_root参数指定基目录

使用相对路径

当使用相对文件路径（如“examples/image.jpg”）时，您有两个选择：

该路径必须相对于服务器正在运行的当前工作目录
或者，您可以指定project_root参数：

# Example with relative path and project_root
result = await image_analysis(
    image="examples/image.jpg",
    project_root="/path/to/your/project",
    query="What is in this image?"
)

这在当前工作目录可能无法预测的应用程序中或当您想使用相对于特定目录的路径引用文件时特别有用。

发展

设置开发环境

# Clone the repository
git clone https://github.com/modelcontextprotocol/mcp-openvision.git
cd mcp-openvision

# Install development dependencies
pip install -e ".[dev]"

代码格式化

该项目使用 Black 进行自动代码格式化。格式化通过 GitHub Actions 强制执行：

推送到存储库的所有代码都会自动用 Black 格式化
对于来自存储库协作者的拉取请求，Black 会格式化代码并直接提交到 PR 分支
对于来自分支的拉取请求，Black 会创建一个新的 PR，其中包含可合并到原始 PR 中的格式化代码

您还可以在提交之前在本地运行 Black 来格式化您的代码：

# Format all Python code in the src and tests directories
black src tests

运行测试

pytest

发布流程

该项目采用自动化发布流程：

按照语义版本控制原则更新pyproject.toml中的版本
- 您可以使用帮助脚本： python scripts/bump_version.py [major|minor|patch]
使用新版本的详细信息更新CHANGELOG.md
- 该脚本还会在 CHANGELOG.md 中创建一个模板条目，您可以填写
提交这些更改并将其推送到main分支
GitHub Actions 工作流程将：
- 检测版本变化
- 自动创建新的 GitHub 版本
- 触发发布到 PyPI 的发布工作流

这种自动化有助于保持一致的发布流程，并确保每个版本都得到正确的版本控制和记录。

支持

如果您发现这个项目有帮助，请考虑给我买一杯咖啡来支持正在进行的开发和维护。

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅LICENSE文件。

mcp-openvision

Integrations