OpenRouter Image MCP Server

🖼️🤖 OpenRouter 图像MCP服务器

](https://badge.fury.io/js/openrouter-image-mcp)   ](https://nodejs.org/)

🔥 为您的AI代理注入强大图像分析能力，使其性能飞跃！ 🔥 火焰（或“火热”、“热烈”的意象，具体根据上下文确定）

一个超高速⚡ MCP（模型上下文协议）服务器，使AI代理能够 看到并理解图像 使用OpenRouter的尖端视觉模型。非常适合截图、照片、图表以及任何视觉内容！ 📸✨

______________________________________________________________________

🌟 什么让这个如此特别？

• 🎯 多模型支持选择Claude、Gemini、GPT-4 Vision等更多选项！
• 🚀 雷电般快速使用TypeScript构建，性能优化
• 🔧 灵活输入支持文件路径、URL和base64数据
• 💰 成本效益高智能模型选择，以实现最佳性价比
• 🛡️ 准备就绪，可投入生产强大的错误处理、重试机制和全面的日志记录
• 🎨 轻松集成与Claude Code、Cline、Cursor等完美兼容！

______________________________________________________________________

🚀 快速入门

先决条件 📋

• Node.js 18岁以上 ⚡
• OpenRouter API密钥 🔑（获取一个于 openrouter.ai（可译为“开放路由人工智能平台”或根据具体语境简化为“开放路由AI”）)
• 您最喜欢的MCP客户端 🤖（克劳德代码，克莱恩，等）

安装 📦

# 🌟 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 .

💡 为何推荐使用 npx无需安装，始终获取最新版本，完美适用于MCP服务器使用！

配置 ⚙️

MCP服务器需要OpenRouter API密钥。您可以采用以下几种方式对其进行配置：

方法1：环境变量（推荐）

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

方法2：.env文件

# 📋 Copy the environment template
cp .env.example .env

# ✏️ Edit with your credentials
nano .env

将您的OpenRouter凭据添加到 .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

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

在您的MCP客户端配置中直接添加API密钥（见下文示例）。

______________________________________________________________________

🏠 房子 本地工作 - 无需重启！ 🎯（目标）

🚀 巨大优势这个MCP服务器在本地运行得非常完美，与……一起 零人工干预 一旦配置好！无需重启，无需手动启动服务器，无需调整设置。它只需 （根据上下文，"works" 可以有多种翻译，以下是几种可能的翻译）✨

🔄 旋转符号（表示循环、重复或刷新） 它是如何自动工作的

1. 🎯 一次性配置 → 一次性设置您的MCP客户端
2. 🚀 自动启动 客户端自动启动服务器
3. 🔧 连接 验证API并即时加载模型
4. 🛠️ 准备就绪，随时可用 → 三款工具均可立即使用

⚡（闪电符号，常用于表示速度、能量或快速动作等） 本地设置的优势

• 即发即弃一次设置，永久无忧
• ⚡ 光速初创公司总准备时间约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 Desktop

添加到 ~/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/mcp.json
• 克林（Cline，人名，具体翻译可能因语境而异，此处为音译）： ~/.cline/mcp.json
• 风帆冲浪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\ 是一个在 Node.js 环境中用于运行 Node.js 脚本的命令行工具，它允许用户执行一次性的脚本或命令，而无需预先安装这些脚本或命令。简单来说，\npx\ 就是帮助你在不安装的情况下运行 Node.js 脚本的工具 （选项1）——这是最简单且最可靠的方法来开始！

💡 灵感/想法/创意的闪光（常用于表示突然想到一个好主意或创意） 本地设置的专家贴士

🎯 路径管理

• 绝对路径效果最佳： /path/to/openrouter-image-mcp/dist/index.js
• 避免使用相对路径在切换目录时可能会中断
• 使用你实际的路径将示例中的项目位置更新为您的实际项目位置

🔧 环境变量

• 设定于 .env 文件确保您的API密钥安全
• 系统中设置的或（OR）值： export OPENROUTER_API_KEY=sk-or-v1-...
• 快速测试跑 OPENROUTER_API_KEY=... node dist/index.js

🚀 快速验证

# 🔍 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"

🐛 解决本地问题

❌“命令未找到”

# ✅ Use absolute path to node
"$(which node)" "/path/to/openrouter-image-mcp/dist/index.js"

❌“文件未找到”

# ✅ Verify the built file exists
ls -la /path/to/openrouter-image-mcp/dist/index.js

# 📝 Rebuild if missing
npm run build

API密钥已要求

# ✅ Check your environment variables
echo $OPENROUTER_API_KEY

# 🔧 Or create .env file
echo "OPENROUTER_API_KEY=sk-or-v1-your-key" > .env

🌟 本地开发工作流程

1. 🛠️ 一次性构建： npm run build
2. ⚙️ 一次性配置为您的AI代理添加MCP配置
3. 🔄 重启代理获取新配置
4. 🎯 立即使用无需手动管理服务器！

______________________________________________________________________

🔥 使用示例

与克劳德代码一起🤖

把这个加到你的 ~/.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 Desktop 🖥️

把这个加到你的 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 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"

______________________________________________________________________

🛠️ 可用工具

🖼️（图片） 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 平台检测
• 🎨 用户界面设计评审
• 👆 用户体验评估
• ♿ 可访问性分析
• 📊 UX启发式评分
• 🚀 性能洞察

______________________________________________________________________

💰 视觉模型推荐

| 💰💰💰 更高级 | ⭐⭐⭐⭐⭐ | 高精度，专业使用 |

• 🎯 推荐模型🆓 从免费模型开始 google/gemini-2.0-flash-exp:free :
• 在大多数使用场景中表现极佳💰 需要时升级
• 只有在需要更高准确度或特定功能时，才考虑转向付费模式🔥 最佳表现 anthropic/claude-3-5-sonnet-20241022 ：

供专业分析使用

• 💡 成本小贴士
• 免费模型完美处理约80%的使用场景
• 付费模型每张图像的费用约为0.001-0.01美元 监控使用情况于

______________________________________________________________________

OpenRouter 控制面板

🛠️ 开发

# 🍴 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

#

______________________________________________________________________

本地设置 🔧

🧪 测试

# 🧪 Run all tests
npm test

# 📊 Run with coverage
npm run test:coverage

# 🔍 Debug mode
DEBUG=* npm test

运行测试套件🧪

# 📸 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

______________________________________________________________________

手动测试🎯

🤝 贡献（或：参与贡献）

______________________________________________________________________

欢迎贡献！克隆仓库，进行修改，然后提交拉取请求。请遵循现有的代码风格，并为新功能添加测试。

📄 支持的图像格式 | 格式 | 扩展名 | MIME 类型 | 状态 | |--------|------------|-----------|--------| .jpg| 🖼️ JPEG（图像格式） | .jpeg ， image/jpeg | ✅ .png | 🖼️ PNG（便携式网络图形） | image/png | ✅ .webp | 🖼️ WebP | image/webp | ✅ .gif | 🖼️ GIF（动图） | image/gif | ✅ | 📏（尺子） 最大尺寸 | - | - | 10兆字节

______________________________________________________________________

(可配置的) |

• 🛡️ 安全与隐私🔐 API密钥
• 仅从环境变量加载🚫 不记录敏感信息
• 个人数据从未记录✅ 输入验证
• 所有参数均已验证📏 尺寸限制
• 可配置的文件大小限制🔒 仅使用HTTPS
• 所有API通信均加密🗑️ 数据清理

______________________________________________________________________

临时文件自动删除

📚 故障排除

🔧 常见问题及解决方案

# ✅ Solution: Set your API key
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# Or add to .env file

“OPENROUTER_API_KEY”环境变量是必需的

# ✅ 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'

🤖 “无效或不支持的模型”

# ✅ Test connection
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/models

📡 "无法连接到OpenRouter API"

# ✅ Increase limit or compress image
export MAX_IMAGE_SIZE=20971520  # 20MB

“图像尺寸超过最大限制”

# 🔍 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

______________________________________________________________________

🐛 调试模式

📄 许可证 这个项目遵循以下许可协议： 麻省理工学院许可证 - 看见 许可证

文件中有详细信息。

💡 建议功能