Skip to main content
Glama
Sign In
enesjakozh

MCP Image Recognition Server

by mario-andreschak
Verified
GitHub
Python
MIT License
9
  • Linux
  • Apple
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Integrations

  • Hosts the MCP server repository, allowing users to clone the codebase for local deployment and configuration

  • Utilizes OpenAI GPT-4 Vision API for image analysis and detailed descriptions from both base64-encoded images and image files

MCP 画像認識サーバー

Anthropic、OpenAI、Cloudflare Workers AI Vision API を使用して画像認識機能を提供する MCP サーバー。バージョン 1.2.1。

著者

もともとこのプロジェクトは@mario-andreschakによって作成されました。ありがとうございます!
現在は@zudsniperによってメンテナンスされています。

特徴

  • Anthropic Claude Vision、OpenAI GPT-4 Vision、または Cloudflare Workers AI llava-1.5-7b-hf を使用した画像の説明
  • Claude Desktop、Cursor、その他のMCP互換クライアントとの簡単な統合
  • Dockerデプロイメントのサポート
  • uvxインストールのサポート
  • 複数の画像形式（JPEG、PNG、GIF、WebP）をサポート
  • 設定可能なプライマリおよびフォールバックプロバイダー
  • Base64およびファイルベースの画像入力のサポート
  • Tesseract OCRを使用したオプションのテキスト抽出

要件

  • Python 3.8以上
  • Tesseract OCR（オプション） - テキスト抽出機能に必要
    • Windows: UB-Mannheim/tesseractからダウンロードしてインストールします。
    • Linux: sudo apt-get install tesseract-ocr
    • macOS: brew install tesseract

インストール

オプション 1: uvx を使用する (Claude Desktop および Cursor に推奨)

  1. uvパッケージ マネージャーをインストールします。
pip install uv
  1. uvx を使用してパッケージをインストールします。
uvx install mcp-image-recognition
  1. 構成セクションの説明に従って環境ファイルを作成して構成します。

オプション2: Dockerを使用する

docker pull zudsniper/mcp-image-recognition:latest # Create a .env file first, then run: docker run -it --env-file .env zudsniper/mcp-image-recognition

オプション3: ソースから

  1. リポジトリをクローンします。
git clone https://github.com/zudsniper/mcp-image-recognition.git cd mcp-image-recognition
  1. 環境ファイルを作成して構成します。
cp .env.example .env # Edit .env with your API keys and preferences
  1. プロジェクトをビルドします。
pip install -e .

統合

クロードデスクトップ統合

  1. Claude >設定>開発者>設定の編集> claude_desktop_config.jsonに移動します。
  2. インライン環境変数を使用して構成を追加します。
{ "mcpServers": { "image-recognition": { "command": "uvx", "args": [ "mcp-image-recognition" ], "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }

カーソル統合

カーソル設定> MCPに移動し、環境変数を貼り付けます。

VISION_PROVIDER=openai OPENAI_API_KEY=your-api-key OPENAI_MODEL=gpt-4o uvx mcp-image-recognition

Docker統合

オプション1: DockerHubイメージを使用する

インライン環境を使用して、Claude Desktop 構成にこれを追加します。

{ "mcpServers": { "image-recognition": { "command": "docker", "args": [ "run", "--rm", "-i", "zudsniper/mcp-image-recognition:latest" ], "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }

Cloudflare の設定の場合:

"env": { "VISION_PROVIDER": "cloudflare", "CLOUDFLARE_API_KEY": "your-api-key", "CLOUDFLARE_ACCOUNT_ID": "your-account-id" }

使用法

サーバーを直接実行する

pip/uvx でインストールした場合:

mcp-image-recognition

ソースディレクトリから:

python -m image_recognition_server.server

Docker の使用:

docker run -it --env-file .env zudsniper/mcp-image-recognition

MCP インスペクターを使用して開発モードで開始します。

npx @modelcontextprotocol/inspector mcp-image-recognition

利用可能なツール

  1. describe_image
    • 目的: チャットに直接アップロードされた画像を分析する
    • 入力: Base64エンコードされた画像データ
    • 出力: 画像の詳細な説明
    • 最適な用途: Claude、Cursor、またはその他のチャットインターフェースに直接アップロードされた画像
  2. describe_image_from_file
    • 目的: ファイルシステムからローカルイメージファイルを処理する
    • 入力: 画像ファイルへのパス
    • 出力: 画像の詳細な説明
    • 最適な用途: ファイルシステムへのアクセスを伴うローカル開発
    • 注: Docker で実行する場合はボリューム マッピングが必要です (Docker ファイル アクセスのセクションを参照)
  3. describe_image_from_url
    • 目的: 手動でダウンロードせずにWeb URLから画像を分析する
    • 入力: 公開されている画像のURL
    • 出力: 画像の詳細な説明
    • 最適な用途: Web画像、スクリーンショット、または公開URLを持つもの
    • 注: レート制限を回避するためにブラウザのようなヘッダーを使用します

環境設定

  • ANTHROPIC_API_KEY : Anthropic API キー。
  • OPENAI_API_KEY : OpenAI API キー。
  • CLOUDFLARE_API_KEY : Cloudflare API キー。
  • CLOUDFLARE_ACCOUNT_ID : Cloudflare アカウント ID。
  • VISION_PROVIDER : プライマリビジョンプロバイダー ( anthropic 、 openai 、またはcloudflare )。
  • FALLBACK_PROVIDER : オプションのフォールバック プロバイダー。
  • LOG_LEVEL : ログレベル (DEBUG、INFO、WARNING、ERROR)。
  • ENABLE_OCR : Tesseract OCR テキスト抽出を有効にします ( trueまたはfalse )。
  • TESSERACT_CMD : Tesseract 実行可能ファイルへのオプションのカスタム パス。
  • OPENAI_MODEL : OpenAIモデル（デフォルト： gpt-4o-mini ）。他のモデルではOpenRouter形式を使用できます（例： anthropic/claude-3.5-sonnet:beta ）。
  • OPENAI_BASE_URL : OpenAI APIのオプションのカスタムベースURL。OpenRouterの場合はhttps://openrouter.ai/api/v1に設定してください。
  • OPENAI_TIMEOUT : OpenAI API のオプションのカスタム タイムアウト (秒単位)。
  • CLOUDFLARE_MODEL : Cloudflare Workers AI モデル (デフォルト: @cf/llava-hf/llava-1.5-7b-hf )。
  • CLOUDFLARE_MAX_TOKENS : 生成するトークンの最大数 (デフォルト: 512 )。
  • CLOUDFLARE_TIMEOUT : Cloudflare API リクエストのタイムアウト（秒単位）（デフォルト: 60 ）。

OpenRouterの使用

OpenRouterを使用すると、OpenAI API形式を使用してさまざまなモデルにアクセスできます。OpenRouterを使用するには、以下の手順に従ってください。

  1. OpenRouter から OpenAI API キーを取得します。
  2. .envファイル内のOPENAI_API_KEY OpenRouter API キーに設定します。
  3. OPENAI_BASE_URL``https://openrouter.ai/api/v1に設定します。
  4. OpenRouter 形式 (例: anthropic/claude-3.5-sonnet:beta ) を使用して、 OPENAI_MODEL目的のモデルに設定します。
  5. VISION_PROVIDER``openaiに設定します。

デフォルトモデル

  • 人類学的: claude-3.5-sonnet-beta
  • OpenAI: gpt-4o-mini
  • Cloudflare ワーカー AI: @cf/llava-hf/llava-1.5-7b-hf
  • OpenRouter: OPENAI_MODELでanthropic/claude-3.5-sonnet:beta形式を使用します。

発達

開発セットアップガイド

開発環境の設定

  1. リポジトリをクローンします。
git clone https://github.com/zudsniper/mcp-image-recognition.git cd mcp-image-recognition
  1. uv を使用したセットアップ (推奨):
# Install uv if not installed pip install uv # Create virtual environment and install deps uv venv uv venv activate uv pip install -e . uv pip install -e ".[dev]"

pip を使用した代替設定:

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -e . # Or alternatively: pip install -r requirements.txt pip install -r requirements-dev.txt
  1. 環境を構成する:
cp .env.example .env # Edit .env with your API keys

VS Code / DevContainer 開発

  1. リモートコンテナ拡張機能を使用してVS Codeをインストールする
  2. VS Codeでプロジェクトフォルダを開きます
  3. プロンプトが表示されたら「コンテナで再度開く」をクリックします
  4. 開発コンテナは、すべての依存関係がインストールされた状態でビルドされ、開きます。

Claude Desktop で開発コンテナを使用する

  1. 環境ファイルを docker compose に渡します。
# Modern Docker Compose V2 syntax docker compose --env-file .env up -d
  1. Claude Desktop の設定に以下を追加します:
{ "mcpServers": { "image-recognition": { "command": "docker", "args": [ "exec", "-i", "mcp-image-recognition-dev", "python", "-m", "image_recognition_server.server" ], "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }

変更をローカルでテストする

  1. MCP サーバーを開発モードで実行します。
# Install the MCP Inspector if you haven't already npm install -g @modelcontextprotocol/inspector # Start the server with the Inspector npx @modelcontextprotocol/inspector mcp-image-recognition
  1. Inspector は Web インターフェイス (通常はhttp://localhost:3000 ) を提供し、次の操作を実行できます。
    • ツールにリクエストを送信する
    • リクエスト/レスポンスログを表示する
    • 実装に関する問題をデバッグする
  2. テスト固有のツール:
    • describe_imageの場合: base64でエンコードされた画像を提供する
    • describe_image_from_fileの場合: ローカル画像ファイルへのパスを指定します
    • describe_image_from_urlの場合: 画像のURLを指定します

Claude Desktop との統合によるテスト

  1. 開発バージョンを使用するために、Claude Desktop の構成を一時的に変更します。
{ "mcpServers": { "image-recognition": { "command": "python", "args": [ "-m", "image_recognition_server.server" ], "cwd": "/path/to/your/mcp-image-recognition", "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }
  1. 変更を適用するには、Claude Desktopを再起動してください。
  2. 会話中に画像をアップロードしたり、画像のURLを提供したりしてテストします

テストの実行

すべてのテストを実行します。

run.bat test

特定のテスト スイートを実行します。

run.bat test server run.bat test anthropic run.bat test openai

Docker サポート

Docker イメージをビルドします。

docker build -t mcp-image-recognition .

コンテナを実行します。

docker run -it --env-file .env mcp-image-recognition

Docker ファイルアクセスの制限

DockerでMCPサーバーを実行する場合、 describe_image_from_fileツールはコンテナ内のファイルにのみアクセスできます。デフォルトでは、コンテナはホストシステム上のファイルにアクセスできません。ローカルファイルへのアクセスを有効にするには、MCPサーバーの設定時にディレクトリを明示的にマッピングする必要があります。

重要事項：Claude Desktop、Cursor、またはチャットに画像をアップロードするその他のプラットフォームを使用する場合、それらの画像はAnthropicのサーバーに保存され、ファイルシステムパスを介してMCPサーバーに直接アクセスすることはできません。これらの場合は、以下の手順を実行してください。

  1. チャットに直接アップロードされた画像には、 describe_imageツール（Base64 エンコードされた画像で動作します）を使用します。
  2. オンラインでホストされている画像には、新しいdescribe_image_from_urlツールを使用します。
  3. ローカルファイルの場合、ディレクトリがDockerコンテナに適切にマッピングされていることを確認してください。

ローカルディレクトリをDockerにマッピングする

Docker コンテナにシステム上の特定のフォルダへのアクセス権を与えるには、MCP サーバ構成を変更してボリューム マッピングを含めます。

{ "mcpServers": { "image-recognition": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/path/on/host:/path/in/container", "zudsniper/mcp-image-recognition:latest" ], "env": { "VISION_PROVIDER": "openai", "OPENAI_API_KEY": "your-api-key", "OPENAI_MODEL": "gpt-4o" } } } }

たとえば、ダウンロード フォルダーをマップするには、次のようにします。

  • Windows: -v "C:\\Users\\YourName\\Downloads:/app/images"
  • macOS/Linux: -v "/Users/YourName/Downloads:/app/images"

次に、コンテナ パスを使用してファイルにアクセスします: /app/images/your_image.jpg

ライセンス

MIT ライセンス - 詳細については LICENSE ファイルを参照してください。

Cloudflare Workers AIの使用

画像認識に Cloudflare Workers AI を使用するには:

  1. Cloudflare ダッシュボードにログインし、アカウントを選択します。
  2. AI > Workers AIに移動します。
  3. **「REST API の使用」**を選択し、Workers AI 権限を持つ API トークンを作成します。
  4. .envファイルで以下を設定します。
    • CLOUDFLARE_API_KEY : Cloudflare APIトークン
    • CLOUDFLARE_ACCOUNT_ID : CloudflareアカウントID
    • VISION_PROVIDER : cloudflareに設定
    • CLOUDFLARE_MODEL : オプション、デフォルトは@cf/llava-hf/llava-1.5-7b-hf

AIアシスタントと併用する

設定が完了すると、AI アシスタント (Claude など) は次の方法で画像を分析できるようになります。

  1. チャットで直接画像をアップロードする
  2. アシスタントは自動的にMCPサーバーを使用して画像を分析します。
  3. アシスタントは、ビジョンAPIの出力に基づいて画像を詳細に説明します。

画像をアップロードした後のプロンプトの例:

Please describe this image in detail.

特定のニーズに合わせてプロンプトをカスタマイズすることもできます。

What text appears in this image?

または

Is there any safety concern in this image?

リリース履歴

  • 1.2.1 (2025-03-28): ドキュメントの再編成と開発コンテナのワークフローの改善
  • 1.2.0 (2025-03-28): httpxとブラウザヘッダーによるURL画像取得を修正し、devcontainerのサポートを追加しました
  • 1.1.0 (2025-03-28): ツールの説明を強化して選択しやすくし、OpenAI SDKを最新バージョンに更新しました
  • 1.0.1 (2025-03-28): URLベースの画像認識機能の追加、Dockerドキュメントの改善、ファイルシステムの制限の修正
  • 1.0.0 (2025-03-28): llava-1.5-7b-hf モデル、Docker サポート、uvx 互換性を備えた Cloudflare Workers AI サポートを追加しました
  • 0.1.2 (2025-02-20): OCRエラー処理の改善とOCR機能の包括的なテストカバレッジの追加
  • 0.1.1 (2025-02-19): 画像からのテキスト抽出のためのTesseract OCRサポートを追加（オプション機能）
  • 0.1.0 (2025-02-19): AnthropicとOpenAIのビジョンサポートを備えた最初のリリース

ライセンス

MIT ライセンス - 詳細については LICENSE ファイルを参照してください。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

新バージョンのリリース

新しいバージョンをリリースするには:

  1. pyproject.tomlとsetup.pyのバージョンを更新します
  2. 変更をreleaseブランチにプッシュする
  3. GitHub Actions は自動的に次の処理を実行します。
    • テストを実行する
    • Dockerイメージをビルドしてプッシュする
    • PyPIに公開する
    • GitHubリリースを作成する

CI/CD に必要なリポジトリ シークレット:

  • DOCKERHUB_USERNAME - Docker Hub のユーザー名
  • DOCKERHUB_TOKEN - Docker Hub アクセストークン
  • PYPI_API_TOKEN - PyPI API トークン

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

Tools

Anthropic Claude Vision および OpenAI GPT-4 Vision API を使用して画像認識機能を提供し、複数の画像形式をサポートし、Tesseract OCR によるオプションのテキスト抽出を提供します。

  1. Authors
    1. Features
      1. Requirements
        1. Installation
          1. Option 1: Using uvx (Recommended for Claude Desktop and Cursor)
          2. Option 2: Using Docker
          3. Option 3: From Source
        2. Integration
          1. Claude Desktop Integration
          2. Cursor Integration
          3. Docker Integration
        3. Usage
          1. Running the Server Directly
          2. Available Tools
          3. Environment Configuration
          4. Using OpenRouter
          5. Default Models
        4. Development
          1. Development Setup Guide
          2. Running Tests
          3. Docker Support
        5. License
          1. Using Cloudflare Workers AI
        6. Using with AI Assistants
          1. Release History
            1. License
              1. Contributing
                1. Releasing New Versions

              Related Resources

              Appeared in Searches

              ID: lit789bgem