OpenRouter Vision MCP server

MCP OpenVision is a Model Context Protocol (MCP) server that provides image analysis capabilities powered by OpenRouter vision models. It enables AI assistants to analyze images through a simple interface within the MCP ecosystem, allowing for detailed image examination without requiring complex integration.

Installation Options

Via Smithery

For Claude Desktop users, you can install MCP OpenVision automatically using Smithery:

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

Using pip

pip install mcp-openvision

Using UV (Recommended)

uv pip install mcp-openvision

Configuration

MCP OpenVision requires an OpenRouter API key and can be configured through environment variables:

• OPENROUTER_API_KEY (required): Your OpenRouter API key
• OPENROUTER_DEFAULT_MODEL (optional): The vision model to use

Supported Vision Models

MCP OpenVision works with any OpenRouter model that supports vision capabilities. The default model is qwen/qwen2.5-vl-32b-instruct:free, but you can specify alternatives:

• qwen/qwen2.5-vl-32b-instruct:free (default)
• anthropic/claude-3-5-sonnet
• anthropic/claude-3-opus
• anthropic/claude-3-sonnet
• openai/gpt-4o

Testing and Integration

Testing with MCP Inspector

Test MCP OpenVision easily with the MCP Inspector tool:

npx @modelcontextprotocol/inspector uvx mcp-openvision

Integration with Claude Desktop or Cursor

1. Edit your MCP configuration file:

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

2. Add the following configuration:

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

Running Locally

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

# Run the server module directly
python -m mcp_openvision

Using Image Analysis

The core functionality of MCP OpenVision is the image_analysis tool, which supports:

• image: Can be provided as:
  • Base64-encoded image data
  • Image URL (http/https)
  • Local file path
• query: Instructions for the image analysis task
• system_prompt: Instructions that define the model's role (optional)
• model: Vision model to use
• temperature: Controls randomness (0.0-1.0)
• max_tokens: Maximum response length

Image Input Types

MCP OpenVision accepts several types of image inputs:

1. Base64-encoded strings
2. Image URLs - must start with http:// or https://
3. File paths:
   • Absolute paths: full paths starting with / (Unix) or drive letter (Windows)
   • Relative paths: paths relative to the current working directory
   • Relative paths with project_root: use the project_root parameter to specify a base directory

Using Relative Paths

When using relative file paths, you have two options:

1. The path must be relative to the current working directory where the server is running
2. Or, you can specify a project_root parameter:

# 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?"
)

Example Usage

# 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"
)

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

# 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",
    system_prompt="You are an expert art historian with deep knowledge of painting techniques."
)

Crafting Effective Queries

The quality of your query significantly impacts the analysis results. A well-crafted query should include:

1. Purpose: Why you're analyzing this image
2. Focus areas: Specific elements or details to examine
3. Required information: The type of information needed
4. Format preferences: How you want the results structured

Examples of Effective Queries

Basic Query	Enhanced Query
"Describe this image"	"Identify all retail products visible in this store shelf image and estimate their price range"
"What's in this image?"	"Analyze this medical scan for abnormalities, focusing on the highlighted area"
"Analyze this chart"	"Extract the numerical data from this bar chart showing quarterly sales, and identify key trends"
"Read the text"	"Transcribe all visible text in this restaurant menu, preserving item names, descriptions, prices"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect