AI导哈

图像分析服务

MCP OpenVision是一个基于OpenRouter视觉模型的图像分析服务，为AI助手提供简单的图像分析接口。

  • by Nazruden
  • Python
  • 本地部署
  • 16 星标
  • 更新于
在 GitHub 查看 Nazruden/mcp-openvision

使用说明

MCP OpenVision

概述

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

安装

通过Smithery安装

通过以下方式自动安装mcp openvision for Claude Desktop 史密瑟里:

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_键 （必需）：您的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检验员测试

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

npx @modelcontextprotocol/inspector uvx mcp-openvision

与Claude桌面或光标集成

  1. 编辑MCP配置文件：

    • 窗户： %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：可以提供为：
      • 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]"

代码格式化

此项目使用黑色进行自动代码格式化。格式是通过GitHub Actions强制执行的：

  • 所有推送到存储库的代码都会自动格式化为黑色
  • 对于来自存储库协作者的pull请求，Black会格式化代码并直接提交给PR分支
  • 对于来自fork的pull请求，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许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP