Openrouter Image MCP

🚀 🖼️🤖 OpenRouter圖像MCP服務器

OpenRouter圖像MCP服務器 是一個超快速的MCP（模型上下文協議）服務器，藉助OpenRouter的前沿視覺模型，讓AI智能體能夠“看到”並理解圖像。適用於截圖、照片、圖表等各類視覺內容，為AI智能體賦予強大的圖像分析能力！

🚀 快速開始

前提條件 📋

• Node.js 18+ ⚡
• OpenRouter API密鑰 🔑（可在 openrouter.ai 獲取）
• 你喜歡的MCP客戶端 🤖（如Claude Code、Cline等）

安裝 📦

# 🌟 選項1：使用npx立即使用（推薦）
npx openrouter-image-mcp

# 🚀 選項2：全局安裝以便頻繁使用
npm install -g openrouter-image-mcp

# 🛠️ 選項3：克隆並在本地構建
git clone https://github.com/JonathanJude/openrouter-image-mcp.git
cd openrouter-image-mcp
npm install
npm run build
npm install -g .

💡 為何推薦npx：無需安裝，始終獲取最新版本，非常適合MCP服務器使用！

配置 ⚙️

MCP服務器需要OpenRouter API密鑰，你可以通過以下幾種方式進行配置：

方法1：環境變量（推薦）

# 🔑 設置你的API密鑰
export OPENROUTER_API_KEY=sk-or-v1-your-api-key-here

# 🎯 設置模型（默認使用免費模型）
export OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free

方法2：.env文件

# 📋 複製環境模板
cp .env.example .env

# ✏️ 使用你的憑證進行編輯
nano .env

在 .env 中添加你的OpenRouter憑證：

# 🔑 必需
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

方法3：在MCP客戶端中直接配置

在你的MCP客戶端配置中直接添加API密鑰（見以下示例）。

✨ 主要特性

• 🎯 多模型支持：可從Claude、Gemini、GPT - 4 Vision等模型中選擇！
• 🚀 閃電般快速：使用TypeScript構建，性能經過優化
• 🔧 靈活輸入：支持文件路徑、URL和Base64數據
• 💰 經濟高效：智能選擇模型，實現最佳性價比
• 🛡️ 生產就緒：具備強大的錯誤處理、重試機制和全面的日誌記錄
• 🎨 易於集成：可與Claude Code、Cline、Cursor等工具無縫協作！

🏠 本地運行 - 無需重啟！ 🎯

🚀 巨大優勢：此MCP服務器在本地配置後無需人工干預即可完美運行！無需重啟，無需手動啟動服務器，無需調整設置，一切自動就緒！ ✨

🔄 自動運行原理

1. 🎯 一次配置 → 一次性設置好你的MCP客戶端
2. 🚀 自動啟動 → 客戶端自動啟動服務器
3. 🔧 自動連接 → 驗證API並立即加載模型
4. 🛠️ 隨時可用 → 所有3個工具立即就緒

⚡ 本地設置優勢

• 🔥 即設即用：一次設置，永久使用
• ⚡ 快速啟動：總就緒時間約5秒
• 🔄 重啟持久：即使筆記本電腦關機也不受影響
• 📱 跨平臺：在任何支持Node.js的操作系統上均可運行
• 🎯 零維護：無需人工干預

🔧 MCP配置

選項1：使用npx（推薦 - 無需安裝）

使用此MCP服務器最簡單的方法是使用npx，它會自動下載並運行軟件包，無需任何安裝：

對於Claude Code

添加到 ~/.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"
        }
      }
    }
  }
}

對於Claude桌面版

添加到 ~/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"
      }
    }
  }
}

對於其他MCP客戶端

• Cursor：~/.cursor/mcp.json
• Cline：~/.cline/mcp.json
• Windsurf：MCP設置文件
• 其他智能體：查看你的智能體的MCP文檔

✨ npx的優勢：

• 🚀 無需安裝 - 立即使用
• 🔄 始終是最新版本 - 自動更新
• 📱 跨平臺 - 在任何安裝了Node.js的地方都能使用
• 🧹 系統整潔 - 無需全局安裝軟件包

選項2：全局安裝（適合頻繁使用的用戶）

如果你計劃頻繁使用此MCP服務器，可以進行全局安裝：

npm install -g openrouter-image-mcp

然後使用以下配置：

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

全局安裝的優勢：

• ⚡ 啟動更快 - 無需下載時間
• 🌐 離線可用 - 安裝後即可使用
• 🔧 命令更簡單 - 配置更簡潔

選項3：本地開發

如果你為了開發而在本地克隆了倉庫：

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

🎯 專業提示：將API密鑰替換為你實際的OpenRouter密鑰。免費模型適用於大多數用例！

💡 建議：從 npx（選項1）開始 - 這是最簡單、最可靠的入門方式！

💡 本地設置專業提示

🎯 路徑管理

• 絕對路徑最佳：/path/to/openrouter-image-mcp/dist/index.js
• 避免相對路徑：切換目錄時可能會出錯
• 使用實際路徑：用你實際的項目位置更新示例

🔧 環境變量

• 在 .env 文件中設置：確保你的API密鑰安全
• 或在系統中設置：export OPENROUTER_API_KEY=sk-or-v1-...
• 快速測試：運行 OPENROUTER_API_KEY=... node dist/index.js

🚀 快速驗證

# 🔍 測試服務器是否正常工作
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

# ✅ 應該看到日誌："Starting OpenRouter Image MCP Server"

🐛 本地問題排查

❌ "Command not found"

# ✅ 使用node的絕對路徑
"$(which node)" "/path/to/openrouter-image-mcp/dist/index.js"

❌ "File not found"

# ✅ 驗證構建文件是否存在
ls -la /path/to/openrouter-image-mcp/dist/index.js

# 📝 如果缺失則重新構建
npm run build

❌ "API key required"

# ✅ 檢查你的環境變量
echo $OPENROUTER_API_KEY

# 🔧 或者創建.env文件
echo "OPENROUTER_API_KEY=sk-or-v1-your-key" > .env

🌟 本地開發工作流程

1. 🛠️ 一次構建：npm run build
2. ⚙️ 一次配置：將MCP配置添加到你的AI智能體
3. 🔄 重啟智能體：使新配置生效
4. 🎯 立即使用：無需手動管理服務器！

💻 使用示例

基礎用法

與Claude Code配合使用 🤖

在你的 ~/.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"
        }
      }
    }
  }
}

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

高級用法

🎯 強大功能示例！

# 📸 分析任何截圖
"Analyze this screenshot: /path/to/screenshot.png"

# 🔍 從圖像中提取文本
"What text do you see in this document: /path/to/scan.jpg"

# 🎨 審查UI設計
"Review this UI mockup for accessibility issues: /path/to/design.png"

# 📱 調試移動應用
"Analyze this mobile app screenshot for UX problems: /path/to/app.png"

# 🌐 分析網頁
"What can you tell me about this webpage: https://example.com/screenshot.png"

🛠️ 可用工具

🖼️ analyze_image - 通用圖像分析

適用於照片、圖表、圖形和一般視覺內容！

參數：

• type 📁 輸入類型：file、url 或 base64
• data 📸 圖像數據（路徑、URL或Base64字符串）
• prompt 💭 自定義分析提示
• format 📊 輸出格式：text 或 json
• maxTokens 🔢 最大響應令牌數（默認：4000）
• temperature 🌡️ 創造力 0 - 2（默認：0.1）

🌐 analyze_webpage_screenshot - 網頁分析專家

專門用於網頁分析和調試！

特性：

• 🎯 佈局分析
• 📱 內容提取
• 🔗 導航審查
• 📝 表單分析
• ♿ 可訪問性評估
• 📊 結構化JSON輸出

📱 analyze_mobile_app_screenshot - 移動應用專家

專門用於移動應用UI/UX分析！

特性：

• 🍎 iOS/🤖 Android平臺檢測
• 🎨 UI設計審查
• 👆 用戶體驗評估
• ♿ 可訪問性分析
• 📊 UX啟發式評分
• 🚀 性能洞察

📚 詳細文檔

💰 視覺模型推薦

模型	成本	視覺質量	適用場景
🆓 google/gemini-2.0-flash-exp:free	免費	⭐⭐⭐⭐⭐	適合初學者！ 通用分析、文檔處理
🆓 meta-llama/llama-3.2-90b-vision-instruct	免費	⭐⭐⭐⭐	圖表、圖形、技術內容
🌟 google/gemini-2.5-flash-lite-preview-09-2025	💰 非常低	⭐⭐⭐⭐⭐	性價比最高！ 低成本高質量
🧠 anthropic/claude-3-5-sonnet-20241022	💰💰 中等	⭐⭐⭐⭐⭐	詳細分析、複雜推理
🔥 anthropic/claude-3-5-haiku-20241022	💰💰💰 較高	⭐⭐⭐⭐⭐	高精度、專業用途

🎯 推薦模型

• 🆓 從免費模型開始：google/gemini-2.0-flash-exp:free 適用於大多數用例
• 💰 需要時升級：僅在需要更高精度或特定功能時選擇付費模型
• 🔥 最佳性能：anthropic/claude-3-5-sonnet-20241022 適用於專業分析

💡 成本提示

• 免費模型可處理約80%的用例
• 付費模型每張圖像成本約為 $0.001 - 0.01
• 在 OpenRouter Dashboard 監控使用情況

🔧 技術細節

開發

# 🍴 克隆倉庫
git clone https://github.com/your-username/openrouter-image-mcp.git
cd openrouter-image-mcp

# 📦 安裝依賴
npm install

# 🔨 構建項目
npm run build

# 🚀 以開發模式啟動
npm run dev

# 🧪 運行測試
npm test

# 🔍 代碼檢查和格式化
npm run lint
npm run format

測試

運行測試套件 🧪

# 🧪 運行所有測試
npm test

# 📊 運行並生成覆蓋率報告
npm run test:coverage

# 🔍 調試模式
DEBUG=* npm test

手動測試 🎯

# 📸 使用示例圖像進行測試
node test-image-analysis.js

# 🔍 測試不同模型
OPENROUTER_MODEL=anthropic/claude-sonnet-4 node test-image-analysis.js

# 🚀 使用URL輸入進行測試
echo '{"type":"url","data":"https://example.com/image.png","prompt":"What do you see?"}' | node dist/index.js

📄 支持的圖像格式

格式	擴展名	MIME類型	狀態
🖼️ JPEG	.jpg, .jpeg	image/jpeg	✅
🖼️ PNG	.png	image/png	✅
🖼️ WebP	.webp	image/webp	✅
🖼️ GIF	.gif	image/gif	✅
📏 最大尺寸	-	-	10MB（可配置）

🛡️ 安全與隱私

• 🔐 API密鑰：僅從環境變量加載
• 🚫 無敏感日誌記錄：絕不記錄個人數據
• ✅ 輸入驗證：驗證所有參數
• 📏 大小限制：可配置文件大小限制
• 🔒 僅支持HTTPS：所有API通信均加密
• 🗑️ 數據清理：臨時文件自動刪除

📚 故障排除

🔧 常見問題及解決方案

🔑 "OPENROUTER_API_KEY environment variable is required"

# ✅ 解決方案：設置你的API密鑰
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# 或者添加到.env文件

🤖 "Invalid or unsupported model"

# ✅ 檢查可用模型
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"

# ✅ 測試連接
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/models

📏 "Image size exceeds maximum"

# ✅ 增加限制或壓縮圖像
export MAX_IMAGE_SIZE=20971520  # 20MB

🐛 調試模式

# 🔍 啟用詳細日誌記錄
export LOG_LEVEL=debug
npm start

# 📊 監控API使用情況
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/auth/key

🤝 貢獻

歡迎貢獻代碼！請fork倉庫，進行更改並提交拉取請求。請遵循現有的代碼風格，併為新功能添加測試。

📄 許可證

本項目採用 MIT許可證 - 詳情請參閱 LICENSE 文件。