OpenRouter Image MCP Server

<div align="center"> # 🖼️🤖 OpenRouter Image MCP Server [](https://badge.fury.io/js/openrouter-image-mcp) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://nodejs.org/) **🔥 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! 📸✨ </div> --- ## 🌟 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](https://openrouter.ai)) - **Your favorite MCP client** 🤖 (Claude Code, Cline, etc.) ### Installation 📦 ```bash # 🌟 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)** ```bash # 🔑 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** ```bash # 📋 Copy the environment template cp .env.example .env # ✏️ Edit with your credentials nano .env ``` Add your OpenRouter credentials to `.env`: ```bash # 🔑 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`: ```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`: ```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: ```bash npm install -g openrouter-image-mcp ``` Then use this configuration: ```json { "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: ```json { "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** ```bash # 🔍 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"** ```bash # ✅ Use absolute path to node "$(which node)" "/path/to/openrouter-image-mcp/dist/index.js" ``` **❌ "File not found"** ```bash # ✅ Verify the built file exists ls -la /path/to/openrouter-image-mcp/dist/index.js # 📝 Rebuild if missing npm run build ``` **❌ "API key required"** ```bash # ✅ 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`: ```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`: ```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! ```bash # 📸 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](https://openrouter.ai) --- ## 🛠️ Development ### Local Setup 🔧 ```bash # 🍴 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 🧪 ```bash # 🧪 Run all tests npm test # 📊 Run with coverage npm run test:coverage # 🔍 Debug mode DEBUG=* npm test ``` ### Manual Testing 🎯 ```bash # 📸 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" ```bash # ✅ Solution: Set your API key export OPENROUTER_API_KEY=sk-or-v1-your-key-here # Or add to .env file ``` #### 🤖 "Invalid or unsupported model" ```bash # ✅ 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" ```bash # ✅ Test connection curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \ https://openrouter.ai/api/v1/models ``` #### 📏 "Image size exceeds maximum" ```bash # ✅ Increase limit or compress image export MAX_IMAGE_SIZE=20971520 # 20MB ``` ### 🐛 Debug Mode ```bash # 🔍 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](LICENSE) file for details. <div align="center"> **🚀 Ready to give your AI agents the power of sight?** **[⭐ Star this repo](https://github.com/your-username/openrouter-image-mcp) • [🐛 Report Issues](https://github.com/your-username/openrouter-image-mcp/issues) • [💡 Suggest Features](https://github.com/your-username/openrouter-image-mcp/discussions)** Made with ❤️ by the open-source community