Openrouter Image MCP

🚀 OpenRouter Image MCP Server

OpenRouter Image MCP Server is a high - speed MCP (Model Context Protocol) server. It empowers AI agents to "see" and understand images by leveraging OpenRouter's advanced vision models. It's suitable for screenshots, photos, diagrams, and all kinds of visual content.

🚀 Quick Start

Prerequisites 📋

• Node.js 18+ ⚡
• OpenRouter API Key 🔑 (Get one at openrouter.ai)
• Your favorite MCP client 🤖 (Claude Code, Cline, etc.)

Installation 📦

# 🌟 Option 1: Use immediately with npx (recommended)
npx openrouter-image-mcp

# 🚀 Option 2: Install globally for frequent use
npm install -g openrouter-image-mcp

# 🛠️ Option 3: Clone and build locally
git clone https://github.com/JonathanJude/openrouter-image-mcp.git
cd openrouter-image-mcp
npm install
npm run build
npm install -g .

💡 Why npx is recommended: No installation required, always gets the latest version, and works perfectly for MCP server usage!

Configuration ⚙️

The MCP server requires an OpenRouter API key. You can configure it in several ways:

Method 1: Environment Variables (Recommended)

# 🔑 Set your API key
export OPENROUTER_API_KEY=sk-or-v1-your-api-key-here

# 🎯 Set model (uses free model by default)
export OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free

Method 2: .env File

# 📋 Copy the environment template
cp .env.example .env

# ✏️ Edit with your credentials
nano .env

Add your OpenRouter credentials to .env:

# 🔑 Required
OPENROUTER_API_KEY=sk-or-v1-your-api-key-here

# 🆓 Model (FREE by default - great for getting started!)
OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free

# 🎛️ Optional settings
LOG_LEVEL=info
MAX_IMAGE_SIZE=10485760
RETRY_ATTEMPTS=3

Method 3: Direct Configuration in MCP Client

Add the API key directly in your MCP client configuration (see examples below).

✨ Features

• 🎯 Multi - Model Support: Choose from Claude, Gemini, GPT - 4 Vision, and more!
• 🚀 Lightning Fast: Built with TypeScript and optimized for performance
• 🔧 Flexible Input: Support for file paths, URLs, and base64 data
• 💰 Cost - Effective: Smart model selection for the best price - to - quality ratio
• 🛡️ Production Ready: Robust error handling, retries, and comprehensive logging
• 🎨 Easy Integration: Works seamlessly with Claude Code, Cline, Cursor, and more!

🏠 Works Locally - No Restarts Needed! 🎯

🚀 HUGE ADVANTAGE: This MCP server works perfectly locally with zero manual intervention once configured! No restarts, no manual server starts, no fiddling with settings. It just works! ✨

🔄 How It Works Automatically

1. 🎯 Configure once → Set up your MCP client one time
2. 🚀 Auto - launches → Client starts the server automatically
3. 🔧 Connects → Validates API and loads models instantly
4. 🛠️ Ready to use → All 3 tools available immediately

⚡ Local Setup Benefits

• 🔥 Fire - and - forget: Set up once, forget forever
• ⚡ Lightning startup: ~5 seconds total ready time
• 🔄 Persistent across restarts: Survives laptop shutdowns
• 📱 Cross - platform: Works on any OS with Node.js
• 🎯 Zero maintenance: No babysitting required

🔧 MCP Configuration

Option 1: Using npx (Recommended - No Installation Required)

The easiest way to use this MCP server is with npx, which automatically downloads and runs the package without any installation:

For Claude Code

Add to ~/.claude.json:

{
  "mcp": {
    "servers": {
      "openrouter-image": {
        "command": "npx",
        "args": ["openrouter-image-mcp"],
        "env": {
          "OPENROUTER_API_KEY": "sk-or-v1-your-api-key-here",
          "OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
        }
      }
    }
  }
}

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openrouter-image": {
      "command": "npx",
      "args": ["openrouter-image-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-api-key-here",
        "OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
      }
    }
  }
}

For Other MCP Clients

• Cursor: ~/.cursor/mcp.json
• Cline: ~/.cline/mcp.json
• Windsurf: MCP settings file
• Other agents: Check your agent's MCP documentation

✨ Benefits of npx:

• 🚀 No installation needed - works immediately
• 🔄 Always latest version - automatically updates
• 📱 Cross - platform - works everywhere Node.js is installed
• 🧹 Clean system - no global packages required

Option 2: Global Installation (For Frequent Users)

If you plan to use this MCP server frequently, install it globally:

npm install -g openrouter-image-mcp

Then use this configuration:

{
  "mcp": {
    "servers": {
      "openrouter-image": {
        "command": "openrouter-image-mcp",
        "env": {
          "OPENROUTER_API_KEY": "sk-or-v1-your-api-key-here",
          "OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
        }
      }
    }
  }
}

Benefits of global installation:

• ⚡ Faster startup - no download time
• 🌐 Works offline - once installed
• 🔧 Simpler command - shorter configuration

Option 3: Local Development

If you cloned the repo locally for development:

{
  "mcpServers": {
    "openrouter-image": {
      "command": "node",
      "args": ["/path/to/openrouter-image-mcp/dist/index.js"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-api-key-here",
        "OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
      }
    }
  }
}

🎯 Pro Tip: Replace the API key with your actual OpenRouter key. The free model works great for most use cases!

💡 Recommendation: Start with npx (Option 1) - it's the easiest and most reliable way to get started!

💡 Pro Tips for Local Setup

🎯 Path Management

• Absolute paths work best: /path/to/openrouter-image-mcp/dist/index.js
• Avoid relative paths: May break when switching directories
• Use your actual path: Update the examples with your real project location

🔧 Environment Variables

• Set in .env file: Keep your API key secure
• OR set in system: export OPENROUTER_API_KEY=sk-or-v1-...
• Test quickly: Run OPENROUTER_API_KEY=... node dist/index.js

🚀 Quick Verification

# 🔍 Test if server works
export OPENROUTER_API_KEY=sk-or-v1-your-key
export OPENROUTER_MODEL=google/gemini-2.5-flash-lite-preview-09-2025
node dist/index.js

# ✅ Should see logs: "Starting OpenRouter Image MCP Server"

🐛 Troubleshooting Local Issues

❌ "Command not found"

# ✅ Use absolute path to node
"$(which node)" "/path/to/openrouter-image-mcp/dist/index.js"

❌ "File not found"

# ✅ Verify the built file exists
ls -la /path/to/openrouter-image-mcp/dist/index.js

# 📝 Rebuild if missing
npm run build

❌ "API key required"

# ✅ Check your environment variables
echo $OPENROUTER_API_KEY

# 🔧 Or create .env file
echo "OPENROUTER_API_KEY=sk-or-v1-your-key" > .env

🌟 Local Development Workflow

1. 🛠️ Build once: npm run build
2. ⚙️ Configure once: Add MCP config to your AI agent
3. 🔄 Restart agent: Pick up the new configuration
4. 🎯 Use immediately: No manual server management needed!

💻 Usage Examples

With Claude Code 🤖

Add this to your ~/.claude.json:

{
  "mcp": {
    "servers": {
      "openrouter-image": {
        "command": "npx",
        "args": ["openrouter-image-mcp"],
        "env": {
          "OPENROUTER_API_KEY": "sk-or-v1-your-api-key-here",
          "OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
        }
      }
    }
  }
}

With Claude Desktop 🖥️

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "openrouter-image": {
      "command": "npx",
      "args": ["openrouter-image-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-your-api-key-here",
        "OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
      }
    }
  }
}

🎯 Amazing Things You Can Do!

# 📸 Analyze any screenshot
"Analyze this screenshot: /path/to/screenshot.png"

# 🔍 Extract text from images
"What text do you see in this document: /path/to/scan.jpg"

# 🎨 Review UI designs
"Review this UI mockup for accessibility issues: /path/to/design.png"

# 📱 Debug mobile apps
"Analyze this mobile app screenshot for UX problems: /path/to/app.png"

# 🌐 Analyze webpages
"What can you tell me about this webpage: https://example.com/screenshot.png"

📚 Documentation

🛠️ Available Tools

🖼️ analyze_image - General Image Analysis

Perfect for photos, diagrams, charts, and general visual content! Parameters:

• type 📁 Input type: file, url, or base64
• data 📸 Image data (path, URL, or base64 string)
• prompt 💭 Custom analysis prompt
• format 📊 Output: text or json
• maxTokens 🔢 Maximum response tokens (default: 4000)
• temperature 🌡️ Creativity 0 - 2 (default: 0.1)

🌐 analyze_webpage_screenshot - Webpage Specialist

Designed specifically for web page analysis and debugging! Features:

• 🎯 Layout analysis
• 📱 Content extraction
• 🔗 Navigation review
• 📝 Form analysis
• ♿ Accessibility evaluation
• 📊 Structured JSON output

📱 analyze_mobile_app_screenshot - Mobile App Expert

Specialized for mobile application UI/UX analysis! Features:

• 🍎 iOS/🤖 Android platform detection
• 🎨 UI design review
• 👆 User experience evaluation
• ♿ Accessibility analysis
• 📊 UX heuristic scoring
• 🚀 Performance insights

💰 Vision Model Recommendations

🎯 Recommended Models

• 🆓 Start with FREE models: google/gemini-2.0-flash-exp:free works excellently for most use cases
• 💰 Upgrade when needed: Move to paid models only if you need higher accuracy or specific features
• 🔥 Best performance: anthropic/claude-3-5-sonnet-20241022 for professional analysis

💡 Cost Tips

• Free models handle ~80% of use cases perfectly
• Paid models cost ~$0.001 - 0.01 per image
• Monitor usage at OpenRouter Dashboard

🔧 Technical Details

🛠️ Development

Local Setup 🔧

# 🍴 Clone the repository
git clone https://github.com/your-username/openrouter-image-mcp.git
cd openrouter-image-mcp

# 📦 Install dependencies
npm install

# 🔨 Build the project
npm run build

# 🚀 Start in development mode
npm run dev

# 🧪 Run tests
npm test

# 🔍 Lint and format
npm run lint
npm run format

🧪 Testing

Run Test Suite 🧪

# 🧪 Run all tests
npm test

# 📊 Run with coverage
npm run test:coverage

# 🔍 Debug mode
DEBUG=* npm test

Manual Testing 🎯

# 📸 Test with a sample image
node test-image-analysis.js

# 🔍 Test different models
OPENROUTER_MODEL=anthropic/claude-sonnet-4 node test-image-analysis.js

# 🚀 Test with URL input
echo '{"type":"url","data":"https://example.com/image.png","prompt":"What do you see?"}' | node dist/index.js

📄 Supported Image Formats

🛡️ Security & Privacy

• 🔐 API Keys: Loaded from environment variables only
• 🚫 No Sensitive Logging: Personal data never logged
• ✅ Input Validation: All parameters validated
• 📏 Size Limits: Configurable file size restrictions
• 🔒 HTTPS Only: All API communications encrypted
• 🗑️ Data Cleanup: Temporary files automatically removed

📚 Troubleshooting

🔧 Common Issues & Solutions

🔑 "OPENROUTER_API_KEY environment variable is required"

# ✅ Solution: Set your API key
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# Or add to .env file

🤖 "Invalid or unsupported model"

# ✅ Check available models
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/models | jq '.data[] | select(.architecture.input_modalities | contains(["image"])) | .id'

📡 "Failed to connect to OpenRouter API"

# ✅ Test connection
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/models

📏 "Image size exceeds maximum"

# ✅ Increase limit or compress image
export MAX_IMAGE_SIZE=20971520  # 20MB

🐛 Debug Mode

# 🔍 Enable detailed logging
export LOG_LEVEL=debug
npm start

# 📊 Monitor API usage
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/auth/key

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.