README.md•6.32 kB
# OpenRouter MCP Multimodal Server
[](https://github.com/stabgan/openrouter-mcp-multimodal/actions/workflows/publish.yml)
[](https://www.npmjs.com/package/@stabgan/openrouter-mcp-multimodal)
[](https://hub.docker.com/r/stabgandocker/openrouter-mcp-multimodal)
An MCP (Model Context Protocol) server that provides chat and image analysis capabilities through OpenRouter.ai's diverse model ecosystem. This server combines text chat functionality with powerful image analysis capabilities.
## Features
- **Text Chat:**
- Direct access to all OpenRouter.ai chat models
- Support for simple text and multimodal conversations
- Configurable temperature and other parameters
- **Image Analysis:**
- Analyze single images with custom questions
- Process multiple images simultaneously
- Automatic image resizing and optimization
- Support for various image sources (local files, URLs, data URLs)
- **Model Selection:**
- Search and filter available models
- Validate model IDs
- Get detailed model information
- Support for default model configuration
- **Performance Optimization:**
- Smart model information caching
- Exponential backoff for retries
- Automatic rate limit handling
## What's New in 1.5.0
- **Improved OS Compatibility:**
- Enhanced path handling for Windows, macOS, and Linux
- Better support for Windows-style paths with drive letters
- Normalized path processing for consistent behavior across platforms
- **MCP Configuration Support:**
- Cursor MCP integration without requiring environment variables
- Direct configuration via MCP parameters
- Flexible API key and model specification options
- **Robust Error Handling:**
- Improved fallback mechanisms for image processing
- Better error reporting with specific diagnostics
- Multiple backup strategies for file reading
- **Image Processing Enhancements:**
- More reliable base64 encoding for all image types
- Fallback options when Sharp module is unavailable
- Better handling of large images with automatic optimization
## Installation
### Option 1: Install via npm
```bash
npm install -g @stabgan/openrouter-mcp-multimodal
```
### Option 2: Run via Docker
```bash
docker run -i -e OPENROUTER_API_KEY=your-api-key-here stabgandocker/openrouter-mcp-multimodal:latest
```
## Quick Start Configuration
### Prerequisites
1. Get your OpenRouter API key from [OpenRouter Keys](https://openrouter.ai/keys)
2. Choose a default model (optional)
### MCP Configuration Options
Add one of the following configurations to your MCP settings file (e.g., `cline_mcp_settings.json` or `claude_desktop_config.json`):
#### Option 1: Using npx (Node.js)
```json
{
"mcpServers": {
"openrouter": {
"command": "npx",
"args": [
"-y",
"@stabgan/openrouter-mcp-multimodal"
],
"env": {
"OPENROUTER_API_KEY": "your-api-key-here",
"DEFAULT_MODEL": "qwen/qwen2.5-vl-32b-instruct:free"
}
}
}
}
```
#### Option 2: Using uv (Python Package Manager)
```json
{
"mcpServers": {
"openrouter": {
"command": "uv",
"args": [
"run",
"-m",
"openrouter_mcp_multimodal"
],
"env": {
"OPENROUTER_API_KEY": "your-api-key-here",
"DEFAULT_MODEL": "qwen/qwen2.5-vl-32b-instruct:free"
}
}
}
}
```
#### Option 3: Using Docker
```json
{
"mcpServers": {
"openrouter": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "OPENROUTER_API_KEY=your-api-key-here",
"-e", "DEFAULT_MODEL=qwen/qwen2.5-vl-32b-instruct:free",
"stabgandocker/openrouter-mcp-multimodal:latest"
]
}
}
}
```
#### Option 4: Using Smithery (recommended)
```json
{
"mcpServers": {
"openrouter": {
"command": "smithery",
"args": [
"run",
"stabgan/openrouter-mcp-multimodal"
],
"env": {
"OPENROUTER_API_KEY": "your-api-key-here",
"DEFAULT_MODEL": "qwen/qwen2.5-vl-32b-instruct:free"
}
}
}
}
```
## Examples
For comprehensive examples of how to use this MCP server, check out the [examples directory](./examples/). We provide:
- JavaScript examples for Node.js applications
- Python examples with interactive chat capabilities
- Code snippets for integrating with various applications
Each example comes with clear documentation and step-by-step instructions.
## Dependencies
This project uses the following key dependencies:
- `@modelcontextprotocol/sdk`: ^1.8.0 - Latest MCP SDK for tool implementation
- `openai`: ^4.89.1 - OpenAI-compatible API client for OpenRouter
- `sharp`: ^0.33.5 - Fast image processing library
- `axios`: ^1.8.4 - HTTP client for API requests
- `node-fetch`: ^3.3.2 - Modern fetch implementation
Node.js 18 or later is required. All dependencies are regularly updated to ensure compatibility and security.
## Available Tools
### mcp_openrouter_chat_completion
Send text or multimodal messages to OpenRouter models:
```javascript
use_mcp_tool({
server_name: "openrouter",
tool_name: "mcp_openrouter_chat_completion",
arguments: {
model: "google/gemini-2.5-pro-exp-03-25:free", // Optional if default is set
messages: [
{
role: "system",
content: "You are a helpful assistant."
},
{
role: "user",
content: "What is the capital of France?"
}
],
temperature: 0.7 // Optional, defaults to 1.0
}
});
```
For multimodal messages with images:
```javascript
use_mcp_tool({
server_name: "openrouter",
tool_name: "mcp_openrouter_chat_completion",
arguments: {
model: "anthropic/claude-3.5-sonnet",
messages: [
{
role: "user",
content: [
{
type: "text",
text: "What's in this image?"
},
{
type: "image_url",
image_url: {
url: "https://example.com/image.jpg"
}
}
]
}
]
}
});
```
