JinDaGe - openrouter-image-mcp MCP Details

article

README

🚀 🖼️🤖 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服务器在本地配置后无需人工干预即可完美运行！无需重启，无需手动启动服务器，无需调整设置，一切自动就绪！ ✨

🔄 自动运行原理

🎯 一次配置 → 一次性设置好你的MCP客户端
🚀 自动启动 → 客户端自动启动服务器
🔧 自动连接 → 验证API并立即加载模型
🛠️ 随时可用 → 所有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

🌟 本地开发工作流程

🛠️ 一次构建：npm run build
⚙️ 一次配置：将MCP配置添加到你的AI智能体
🔄 重启智能体：使新配置生效
🎯 立即使用：无需手动管理服务器！

💻 使用示例

基础用法

与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 文件。

🚀 准备好为你的AI智能体赋予视觉能力了吗？

⭐ 给这个仓库加星 • 🐛 报告问题 • 💡 提出功能建议

由开源社区用心打造 ❤️