Openrouter Image MCP

🚀 🖼️🤖 OpenRouter Image MCP Server

🔥 強力な画像分析機能でAIエージェントを強化しましょう！ 🔥

OpenRouterの最先端のビジョンモデルを使用して、AIエージェントが画像を「見て理解する」ことを可能にする、超高速⚡のMCP（Model Context Protocol）サーバーです。スクリーンショット、写真、図表、およびあらゆる視覚コンテンツに最適です！ 📸✨

🚀 クイックスタート

前提条件 📋

• 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クライアントで直接設定

APIキーをMCPクライアントの設定に直接追加します（以下の例を参照）。

🏠 ローカルで動作 - 再起動不要！ 🎯

🚀 大きな利点: このMCPサーバーは、一度設定すれば、手動介入なしでローカルで完璧に動作します！再起動や手動でのサーバー起動、設定のいじりは必要ありません。ただ動作します！ ✨

🔄 自動動作の仕組み

1. 🎯 一度設定 → MCPクライアントを一度設定します
2. 🚀 自動起動 → クライアントが自動的にサーバーを起動します
3. 🔧 接続 → APIを検証し、すぐにモデルを読み込みます
4. 🛠️ 使用可能 → すべての3つのツールがすぐに使用可能になります

⚡ ローカルセットアップの利点

• 🔥 セットアップ後は放置可能: 一度設定すれば、忘れてしまえます
• ⚡ 超高速起動: 合計約5秒で準備完了
• 🔄 再起動を通じて持続: ノートパソコンのシャットダウンにも耐えます
• 📱 クロスプラットフォーム: Node.jsがインストールされたあらゆるOSで動作します
• 🎯 メンテナンス不要: 手入れは一切必要ありません

🔧 MCP設定

オプション1: npxを使用する（推奨 - インストール不要）

このMCPサーバーを使用する最も簡単な方法は、npxを使用することです。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: ~/.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"
      }
    }
  }
}

⚠️ 重要な注意

実際のOpenRouterキーでAPIキーを置き換えてください。無料モデルはほとんどのユースケースでうまく機能します！

💡 使用アドバイス

最初は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. ⚙️ 一度設定: AIエージェントにMCP設定を追加します
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 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 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 はほとんどのユースケースで優れた性能を発揮します
• 💰 必要に応じてアップグレード: より高い精度または特定の機能が必要な場合のみ、有料モデルに移行します
• 🔥 最高のパフォーマンス: 専門的な分析には anthropic/claude-3-5-sonnet-20241022 を使用します

💡 コストヒント

• 無料モデルは約80％のユースケースを完璧に処理します
• 有料モデルのコストは画像1枚あたり約$0.001-0.01です
• OpenRouterダッシュボード で使用状況を監視してください

🛠️ 開発

ローカルセットアップ 🔧

# 🍴 リポジトリをクローン
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

🤝 コントリビューション

コントリビューションを歓迎します！リポジトリをフォークし、変更を加えて、プルリクエストを送信してください。既存のコードスタイルに従い、新機能にはテストを追加してください。

📄 サポートされる画像形式

🛡️ セキュリティとプライバシー

• 🔐 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

📄 ライセンス

このプロジェクトは MITライセンス の下でライセンスされています - 詳細については LICENSE ファイルを参照してください。