TheNomadInOrbit/Vision-MCP-Server

Vision MCP Server

Ever wanted to use a model like GLM-4.6 or other great AI models that just don't have vision capabilities? This MCP server solves that problem by adding vision capabilities to any model through OpenRouter's vision models.

The Problem

Some really good AI models don't support vision. You're stuck choosing between your preferred model or vision capabilities. This server bridges that gap by providing seamless vision capabilities through OpenRouter's vision models.

The Solution

This MCP server provides a simple analyze_image tool that can:

• Analyze images from URLs, file paths, or base64 data
• Use any vision model available on OpenRouter (Claude 3.5 Sonnet, GPT-4 Vision, etc.)
• Return detailed analysis results
• Handle errors gracefully with proper validation

System Requirements

Before installing, make sure you have:

• Node.js 18.0.0 or higher (recommended: Node.js 20+)
• npm 8.0.0 or higher (comes with Node.js)

Check Your Versions

node --version    # Should show v18.0.0 or higher
npm --version     # Should show 8.0.0 or higher

Install/Update Node.js

If you need to install or update Node.js:

1. Download from official site: nodejs.org (recommended for beginners)
2. Using Node Version Manager (nvm):

   # Install nvm first, then:
   nvm install 20
   nvm use 20
   

3. Using package managers:
   • macOS: brew install node
   • Windows: winget install OpenJS.NodeJS
   • Ubuntu/Debian: sudo apt install nodejs npm

Important: This server is written in TypeScript and uses dependencies (like node-fetch v3) that require Node.js 18+. Older versions (like Node.js 16 or below) will not work.

Quick Start

Step 1: Get Your OpenRouter API Key

1. Go to OpenRouter
2. Sign up or log in to your account
3. Navigate to "Keys" in your dashboard
4. Click "Create Key"
5. Copy your API key (starts with sk-or-v1-...)
6. Keep this key safe - you'll need it in Step 3

Step 2: Install the MCP Server

Option A: Install from npm (Recommended)

npm install -g @thenomadinorbit/vision-mcp-server

Success! The package is now globally available as vision-mcp command.

Option B: Install from Source (Development)

git clone https://github.com/TheNomadInOrbit/vision-mcp-server.git
cd vision-mcp-server
npm install
npm run build
npm install -g .

Note: Use this method if you want to modify the source code or contribute to the project.

Step 3: Configure Your MCP Client

Add this server configuration to your MCP client:

{
  "mcpServers": {
    "vision-analyzer": {
      "command": "vision-mcp",
      "type": "stdio",
      "timeout": 60,
      "disabled": false,
      "autoApprove": [],
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "OPENROUTER_MODEL": "anthropic/claude-3-5-sonnet"
      }
    }
  }
}

Step 4: Test Your Installation

Important: The vision-mcp command requires an OpenRouter API key to run. You cannot test it directly without configuration.

Quick Test (with your API key):

OPENROUTER_API_KEY="your_api_key_here" vision-mcp --help

You should see the server start up with logs like:

Application initialized successfully
Starting Vision MCP Server...
MCP server started successfully
Vision MCP Server is running on stdio

Press Ctrl+C to stop the test.

What happens if you run vision-mcp without the API key?

vision-mcp

You'll get this error (this is normal and expected):

Error: OPENROUTER_API_KEY environment variable is required

This means the installation worked! The server is just protecting you from running without proper configuration.

Verify Installation Status:

# Check if the command is available
which vision-mcp

# Check if the package is installed
npm list -g @thenomadinorbit/vision-mcp-server

🔧 Configuration Options

Basic Configuration

• "vision-analyzer" - Server name (you can change this to anything you like)
• "command": "vision-mcp" - Required: The global command to run the server
• "type": "stdio" - Required: Communication protocol for MCP
• "timeout": 60 - Optional: Timeout in seconds (default: 60)
• "disabled": false - Optional: Set to true to disable the server

Auto-Approve Settings

Configure which tools can run without asking for permission:

"autoApprove": []

Options:

• [] (empty) - Requires approval for all tools (safest)
• ["list_models"] - Auto-approve listing available models only
• ["analyze_image"] - Auto-approve vision analysis (convenient but less safe)
• ["analyze_image", "list_models"] - Auto-approve all tools (most convenient)

Model Configuration

You can use any vision model from OpenRouter:

"env": {
  "OPENROUTER_API_KEY": "your_api_key_here",
  "OPENROUTER_MODEL": "anthropic/claude-3-5-sonnet"
}

Popular Models:

• anthropic/claude-3.5-sonnet (recommended - best for vision)
• openai/gpt-4o-2024-08-06 (excellent vision capabilities)
• google/gemini-2.0-flash-001 (fast and cost-effective)
• anthropic/claude-3-opus (most powerful for complex analysis)

Complete Example Configuration

{
  "mcpServers": {
    "vision-analyzer": {
      "command": "vision-mcp",
      "type": "stdio",
      "timeout": 60,
      "disabled": false,
      "autoApprove": ["list_models"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-actual-key-here",
        "OPENROUTER_MODEL": "anthropic/claude-3.5-sonnet",
        "MAX_IMAGE_SIZE": "10485760"
      }
    }
  }
}

Available Tools

Once configured, your AI assistant can use these tools:

analyze_image

Analyze images with AI vision models

• Input: Image URL, file path, or base64 data
• Output: Detailed analysis of the image content

list_models

List all available vision models from OpenRouter

• Input: None
• Output: Array of available models with their capabilities

Usage Examples

Once configured, you can ask your AI assistant to analyze images like this:

Real-World Example

You: "Can you analyze this image: https://example.com/image.jpg"

What happens behind the scenes:

1. Your AI assistant receives your request
2. It calls the analyze_image tool from this MCP server
3. This server downloads the image and sends it to OpenRouter's vision model
4. The vision model analyzes the image
5. Results are returned to your AI assistant
6. Your AI assistant presents the analysis to you

You see: Detailed image analysis from your AI assistant You don't see: All the technical MCP communication happening behind the scenes

Example Conversations

Analyze an image from URL:

"Can you analyze this image: https://example.com/image.jpg"

Analyze a local image:

"Please analyze the image at /Users/username/Pictures/photo.png"

Get available models:

"What vision models are available?"

Detailed analysis:

"Analyze this image and tell me about the objects, colors, and mood: https://example.com/artwork.jpg"

Compare images:

"Can you analyze these two images and tell me the differences: image1.jpg and image2.jpg"

Environment Variables

You can customize the server with these environment variables:

Troubleshooting

Common Mistakes

"I installed it but vision-mcp gives an error!"

The Error:

Error: OPENROUTER_API_KEY environment variable is required

Why this happens: You're trying to run vision-mcp directly from the command line. This MCP server is designed to be used through an MCP client (like Claude Code), not run directly.

The Fix:

1. Correct: Configure it in your MCP client (Step 3 above)
2. Incorrect: Running vision-mcp directly in terminal

Quick test only: If you want to test the installation, use:

OPENROUTER_API_KEY="your_key" vision-mcp --help

"How do I actually use this?"

This server doesn't have a web interface or CLI commands. It's an MCP server that adds vision capabilities to your AI assistant through the MCP protocol.

Workflow:

1. Install the server globally (npm install -g @thenomadinorbit/vision-mcp-server)
2. Configure it in your MCP client (Claude Desktop, etc.)
3. Ask your AI assistant to analyze images
4. The AI assistant uses this server behind the scenes

Command not found: vision-mcp

1. For npm installation: Make sure you ran npm install -g @thenomadinorbit/vision-mcp-server
2. For source installation: Make sure you ran npm install -g . after building
3. Try running npm list -g @thenomadinorbit/vision-mcp-server to verify installation
4. Restart your terminal

"Server not found" or "Connection failed"

1. Verify the command is vision-mcp (not a file path)
2. Make sure you ran npm run build
3. Check that the global installation worked: which vision-mcp
4. Restart your MCP client

"API key invalid"

1. Double-check your OpenRouter API key
2. Make sure it starts with sk-or-v1-
3. Verify you have credits in your OpenRouter account

"Vision analysis failed"

1. Try with a smaller image (under 10MB)
2. Make sure the image format is supported (JPG, PNG, WebP)
3. Check your OpenRouter account has sufficient credits

Still not working?

1. Check your MCP client logs for error messages
2. Make sure your configuration file has valid JSON syntax
3. Try restarting your computer

Reporting Issues

Found a bug or have a suggestion? Feel free to open an issue with:

• Clear description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Your environment details (Node.js version, OS, etc.)

Development Setup

If you want to fork and modify for your own use:

git clone https://github.com/TheNomadInOrbit/vision-mcp-server.git
cd vision-mcp-server
npm install
npm run build

Security

If you discover a security vulnerability, please open a security issue with the "security" label.

Changelog

See for a detailed history of changes.

License

MIT - Use it however you want.