MCP OpenVision

概览

MCP OpenVision 是一个基于 Model Context Protocol (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（推荐）

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 集成

1. 编辑您的 MCP 配置文件：

   • Windows: %USERPROFILE%\.cursor\mcp.json
   • macOS: ~/.cursor/mcp.json 或 ~/Library/Application Support/Claude/claude_desktop_config.json

2. 添加以下配置：

{
  "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 编码的图像数据
    • 图像 URL (http/https)
    • 本地文件路径
  • query: 用户对图像分析任务的指令
  • system_prompt: 定义模型角色和行为的指令（可选）
  • model: 要使用的视觉模型
  • temperature: 控制随机性 (0.0-1.0)
  • max_tokens: 最大响应长度

构建有效的查询

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

1. 目的：你为什么要分析这张图片
2. 关注区域：需要特别注意的具体元素或细节
3. 所需信息：你需要提取的信息类型
4. 格式偏好：你希望结果如何结构化

有效查询示例

基本查询	增强查询
"描述这张图片"	"识别这张商店货架图片中所有可见的零售产品，并估计它们的价格范围"
"这张图片里有什么？"	"分析这张医学扫描图中的异常情况，重点关注突出显示的区域并提供可能的诊断"
"分析这个图表"	"从这个显示季度销售的条形图中提取数值数据，并确定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 工具接受多种类型的图像输入：

1. Base64编码的字符串
2. 图像URL - 必须以 http:// 或 https:// 开头
3. 文件路径：
   • 绝对路径：从 /（Unix）或驱动器字母（Windows）开始的完整路径
   • 相对路径：相对于当前工作目录的路径
   • 带有 project_root 的相对路径：使用 project_root 参数指定一个基础目录

使用相对路径

当使用相对文件路径（如 "examples/image.jpg"）时，你有两个选项：

1. 路径必须相对于运行服务器的当前工作目录
2. 或者，你可以指定一个 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 分支
• 对于来自 fork 的拉取请求，Black 会创建一个新的包含格式化代码的 PR，可以合并到原始 PR 中

你也可以在本地运行 Black 来在提交前格式化你的代码：

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

运行测试

pytest

发布流程

本项目使用自动化发布流程：

1. 根据语义化版本控制原则更新 pyproject.toml 中的版本号
   • 你可以使用辅助脚本：python scripts/bump_version.py [major|minor|patch]
2. 更新 CHANGELOG.md，添加新版本的详细信息
   • 脚本还会在 CHANGELOG.md 中创建一个模板条目供你填写
3. 将这些更改提交并推送到 main 分支
4. GitHub Actions 工作流将：
   • 检测到版本变更
   • 自动创建一个新的 GitHub 发布版本
   • 触发发布工作流，将包发布到 PyPI

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

支持

如果你觉得这个项目对你有帮助，请考虑买杯咖啡支持项目的持续开发和维护。

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。