🖼️🤖 OpenRouter Image MCP Server

npm version License: MIT TypeScript Node.js

🔥 Supercharge your AI agents with powerful image analysis capabilities! 🔥

A blazing-fast ⚡ MCP (Model Context Protocol) server that enables AI agents to see and understand images using OpenRouter's cutting-edge vision models. Perfect for screenshots, photos, diagrams, and any visual content! 📸✨

🌟 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

🎯 Configure once → Set up your MCP client one time
🚀 Auto-launches → Client starts the server automatically
🔧 Connects → Validates API and loads models instantly
🛠️ 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 : 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

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

🔥 Usage Examples

With Claude Code 🤖

Add this to your ~/.claude.json:

With Claude Desktop 🖥️

Add this to your claude_desktop_config.json:

🎯 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
🔗 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

Model	Cost	Vision Quality	Best For
🆓 `google/gemini-2.0-flash-exp:free`	FREE	⭐⭐⭐⭐⭐	Great for beginners! General analysis, docs
🆓 `meta-llama/llama-3.2-90b-vision-instruct`	FREE	⭐⭐⭐⭐	Charts, diagrams, technical content
🌟 `google/gemini-2.5-flash-lite-preview-09-2025`	💰 Very Low	⭐⭐⭐⭐⭐	Best value! High quality at low cost
🧠 `anthropic/claude-3-5-sonnet-20241022`	💰💰 Medium	⭐⭐⭐⭐⭐	Detailed analysis, complex reasoning
🔥 `anthropic/claude-3-5-haiku-20241022`	💰💰💰 Higher	⭐⭐⭐⭐⭐	High accuracy, professional use

🎯 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

🛠️ 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

🤝 Contributing

Contributions welcome! Fork the repo, make changes, and submit a pull request. Please follow the existing code style and add tests for new features.

📄 Supported Image Formats

Format	Extension	MIME Type	Status
🖼️ JPEG	`.jpg` , `.jpeg`	`image/jpeg`	✅
🖼️ PNG	`.png`	`image/png`	✅
🖼️ WebP	`.webp`	`image/webp`	✅
🖼️ GIF	`.gif`	`image/gif`	✅
📏 Max Size	-	-	10MB (configurable)

🛡️ 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.

🚀 Ready to give your AI agents the power of sight?

⭐ Star this repo

Made with ❤️ by the open-source community

Deploy Server

HTTP connection URL

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Enables AI agents to analyze and understand images using OpenRouter's vision models. Supports screenshots, photos, diagrams, and web content with specialized tools for webpage and mobile app analysis.