Skip to main content
Glama
enesjakozh
Nazruden

mcp-openvision

by Nazruden
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

MCP OpenVision

CI PyPI 版本 Python 版本 许可证：MIT 给我买杯咖啡 铁匠徽章

概述

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

Related MCP server: MCP OpenVision

安装

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

  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编码的图像数据

      • 图片网址 (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 分支

  • 对于来自分支的拉取请求，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文件。

Available Tools

1 tool
image_analysisA
Analyze an image using OpenRouter's vision capabilities.

This tool allows you to send an image to OpenRouter's vision models for analysis.
You provide a query to guide the analysis and can optionally customize the system prompt
for more control over the model's behavior.

Args:
    image: The image as a base64-encoded string, URL, or local file path
    query: Text prompt to guide the image analysis. For best results, provide context
           about why you're analyzing the image and what specific information you need.
           Including details about your purpose and required focus areas leads to more
           relevant and useful responses.
    system_prompt: Instructions for the model defining its role and behavior
    model: The vision model to use (defaults to the value set by OPENROUTER_DEFAULT_MODEL)
    max_tokens: Maximum number of tokens in the response (100-4000)
    temperature: Temperature parameter for generation (0.0-1.0)
    top_p: Optional nucleus sampling parameter (0.0-1.0)
    presence_penalty: Optional penalty for new tokens based on presence in text so far (0.0-2.0)
    frequency_penalty: Optional penalty for new tokens based on frequency in text so far (0.0-2.0)
    project_root: Optional root directory to resolve relative image paths against

Returns:
    The analysis result as text

Examples:
    Basic usage with a file path:
        image_analysis(image="path/to/image.jpg", query="Describe this image in detail")

    Basic usage with an image URL:
        image_analysis(image="https://example.com/image.jpg", query="Describe this image in detail")

    Basic usage with a relative path and project root:
        image_analysis(image="examples/image.jpg", project_root="/path/to/project", query="Describe this image in detail")

    Usage with a detailed contextual query:
        image_analysis(
            image="path/to/image.jpg",
            query="Analyze this product packaging design for a fitness supplement. Identify all nutritional claims,
                  certifications, and health icons. Assess the visual hierarchy and how the key selling points
                  are communicated. This is for a competitive analysis project."
        )

    Usage with custom system prompt:
        image_analysis(
            image="path/to/image.jpg",
            query="What objects can you see in this image?",
            system_prompt="You are an expert at identifying objects in images. Focus on listing all visible objects."
        )
ParametersJSON Schema
NameRequiredDescriptionDefault
imageYes
queryNoDescribe this image in detail
system_promptNoYou are an expert vision analyzer with exceptional attention to detail. Your purpose is to provide accurate, comprehensive descriptions of images that help AI agents understand visual content they cannot directly perceive. Focus on describing all relevant elements in the image - objects, people, text, colors, spatial relationships, actions, and context. Be precise but concise, organizing information from most to least important. Avoid making assumptions beyond what's visible and clearly indicate any uncertainty. When text appears in images, transcribe it verbatim within quotes. Respond only with factual descriptions without subjective judgments or creative embellishments. Your descriptions should enable an agent to make informed decisions based solely on your analysis.
modelNo
max_tokensNo
temperatureNo
top_pNo
presence_penaltyNo
frequency_penaltyNo
project_rootNo

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries full burden for behavioral disclosure. It explains that the tool uses OpenRouter's vision models and returns text, and it lists default parameter values. However, it lacks information about external API dependencies, potential latency, failure modes, or rate limits, which are important for an agent to understand. The description is adequate but not comprehensive in this regard.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear introductory sentence, parameter list, return value, and examples. While it is verbose in parts (e.g., the query parameter explanation is lengthy), every sentence adds value. It could be slightly more concise, but it is appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (10 parameters, no output schema, no annotations), the description is highly complete. It explains all parameters, specifies return type ('The analysis result as text'), and provides comprehensive examples covering various use cases. The default system prompt is also elaborated, which adds valuable context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate entirely. It does so excellently by providing detailed explanations for all 10 parameters, including their purpose, defaults, and constraints. For example, it explains that 'query' should include context for better results and provides examples. This enables correct parameter usage without relying on the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Analyze an image using OpenRouter's vision capabilities.' It specifies the action (analyze), resource (image), and technology (OpenRouter's vision), leaving no ambiguity. With no sibling tools, differentiation is not needed, but the purpose is specific and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage guidance through detailed parameter descriptions and multiple examples covering file paths, URLs, contextual queries, and custom system prompts. However, it does not explicitly state when not to use this tool or mention alternatives, though none exist. 'Clear context, no exclusions' accurately reflects this.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation5/5

With only one tool, there is no possibility of confusion between tools. The tool's purpose is clear and unique.

Naming Consistency5/5

A single tool means no inconsistency in naming patterns. The name 'image_analysis' is descriptive and follows a common noun_noun convention.

Tool Count3/5

A single tool for a vision server feels slightly thin. While the one tool is comprehensive, the server scope seems narrow; typically 3-15 tools are expected for a well-scoped server.

Completeness2/5

The server only offers image analysis. Missing other common vision operations like model listing, batch processing, or generation. The surface is incomplete for a vision-focused server.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Nazruden/mcp-openvision'

If you have feedback or need assistance with the MCP directory API, please join our Discord server