home / mcp / openrouter image mcp server

OpenRouter Image MCP Server

🖼️ OpenRouter Image MCP: Supercharge AI agents with vision! 🔥 Analyze screenshots, debug UI, extract text from images. Works locally with zero restarts - configure once and forget! 📸✨

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jonathanjude-openrouter-image-mcp": {
      "command": "npx",
      "args": [
        "openrouter-image-mcp"
      ],
      "env": {
        "LOG_LEVEL": "info",
        "MAX_IMAGE_SIZE": "10485760",
        "RETRY_ATTEMPTS": "3",
        "OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free",
        "OPENROUTER_API_KEY": "sk-or-v1-your-api-key-here"
      }
    }
  }
}

You can empower your AI agents to see and interpret images by running an OpenRouter Image MCP Server. It connects your MCP client to OpenRouter vision models, enabling fast image analysis from files, URLs, or base64 data. Use this to analyze screenshots, photos, diagrams, and more, while enjoying flexible input options and cost-conscious model selection.

How to use

You interact with the server through an MCP client. Configure your client once, then start using the image analysis tools without managing the server manually. The server exposes several specialized tools that let you analyze images, webpages, or mobile app screenshots. Start with a simple setup using npx, then connect your client to the local MCP instance or a remote MCP endpoint if you choose.

Key capabilities include analyzing general images, extracting text from images, reviewing UI designs, and debugging web pages or mobile app screenshots. You can specify input types such as file paths, URLs, or base64 data and choose a model that balances cost and quality.

How to install

Prerequisites you need before installing the MCP server.

# Prerequisites
- Node.js 18+
- An OpenRouter API key
- A MCP client you plan to use (Claude Code, Cline, Cursor, etc.)

Choose one of the installation options below. Implement the steps exactly as shown to ensure the server runs smoothly.

# Option 1: Run 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 .

Configuration and usage notes

The MCP server requires an OpenRouter API key. You can configure it in multiple ways to suit your workflow.

# Method 1: Environment variables (recommended)
export OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
export OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free

Alternative configuration via a .env file or directly in your MCP client is also supported. Here is an example .env setup.

# .env example
OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free
LOG_LEVEL=info
MAX_IMAGE_SIZE=10485760
RETRY_ATTEMPTS=3

Security and best practices

Keep your API key secure by storing it in environment variables or a secured .env file. The server validates inputs, enforces size limits on images, and uses HTTPS for all API communications. Temporary files are cleaned up automatically.

Troubleshooting

If you encounter issues, verify your environment variables and input parameters first. Common problems include missing API keys, invalid models, and image size limits. Use a debug mode to gain more insight into errors.

# Quick checks
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
# Look for: Starting OpenRouter Image MCP Server

Available tools

The MCP server exposes image analysis tools you can call from your MCP client. See the tool descriptions below for how to use them in prompts.

Available tools

analyze_image

General image analysis tool that accepts image data as file, URL, or base64 and returns either text or JSON results with an optional custom prompt.

analyze_webpage_screenshot

Webpage-focused analysis that can extract layout, content, navigation, forms, accessibility data, and outputs structured JSON.

analyze_mobile_app_screenshot

Mobile UI/UX analysis tool that detects platform, evaluates UI design, accessibility, UX heuristics, and performance insights.