OpenRouter Image Analysis

---

🌟 What Makes This Special?

• 🎯 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!

---

🚀 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).

---

🏠 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"

---

🛠️ 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
• 🔗 Navi

---

README truncated. View full README on GitHub.