# πŸ–ΌοΈπŸ€– OpenRouter Image MCP Server [![npm version](https://badge.fury.io/js/openrouter-image-mcp.svg)](https://badge.fury.io/js/openrouter-image-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Node.js](https://img.shields.io/badge/Node.js-43853D?logo=node.js&logoColor=white)](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! πŸ“Έβœ¨
--- ## 🌟 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.
**πŸš€ 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