MCP OpenVision

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 环境变量来指定自定义模型，也可以直接向 image_analysis 函数传入 model 参数。

使用方法

使用 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 文件。