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](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 - 🔗 Navi ---