OpenRouter Image MCP Server

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

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:

{
  "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 .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**

#  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

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:

{
  "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:

{
  "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!

#  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 Report Issues Suggest Features

Made with by the open-source community