---

🌟 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

$3

- Node.js 18+ ⚡
- OpenRouter API Key 🔑 (Get one at openrouter.ai)
- Your favorite MCP client 🤖 (Claude Code, Cline, etc.)

$3

``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!

$3

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! ✨

$3

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

$3

- 🔥 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

$3

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

$3

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

$3

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!

$3

#### 🎯 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
`

$3

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

$3

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"
}
}
}
}
}
`

$3

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"
}
}
}
}
`

$3

`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

$3

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)

$3

Designed specifically for web page analysis and debugging!

Features:
- 🎯 Layout analysis
- 📱 Content extraction
- 🔗 Navigation review
- 📝 Form analysis
- ♿ Accessibility evaluation
- 📊 Structured JSON output

$3

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 |

$3


- 🆓 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

$3

- Free models handle ~80% of use cases perfectly
- Paid models cost ~$0.001-0.01 per image
- Monitor usage at OpenRouter Dashboard

---

🛠️ Development

$3

`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

$3

`bash


🧪 Run all tests

npm test

📊 Run with coverage

npm run test:coverage

🔍 Debug mode

DEBUG=* npm test
`

$3

`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

$3

#### 🔑 "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
`

$3

`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 file for details.