Local Image Search (Japanese) MCP Server

日本語に特化した CLIP モデル (line-corporation/clip-japanese-base) を利用し、日本語の自然言語（テキスト）によるローカル画像の類似度検索を提供する MCP (Model Context Protocol) サーバーです。

特徴

• 日本語による画像検索: 自然な日本語クエリ（例：「赤い髪の女の子」「夜のネオン街」など）でローカル画像を検索可能。
• 効率的なインデックス更新: 画像のスキャン結果と特徴ベクトル（Embedding）を SQLite データベースにキャッシュし、変更・追加があった画像のみを差分更新。
• 高速な検索: インデックスされた特徴ベクトルを起動時にメモリ上に展開し、コサイン類似度計算を行うことでミリ秒単位の高速な検索を実現。
• MCP ＆ HTTP サーバーのハイブリッド:
  • Claude Desktop 等から呼び出し可能な MCP サーバーとしての動作。
  • 検索 API エンドポイント (/api/search) および、結果画像配信用エンドポイント (/image) を内蔵。

---

構成ファイル

• update_index.py: 指定したフォルダ内の画像をスキャンし、特徴ベクトルを抽出してデータベースを構築・更新する CLI スクリプト。
• server.py: SQLite データベースを読み込み、MCP ツールおよび HTTP 検索/画像配信 API を提供するサーバープログラム。
• requirements.txt: 実行に必要な依存パッケージ一覧。

---

準備

1. 動作環境

• Python 3.10 以上
• GPU 環境推奨 (CUDA が利用可能な場合、自動的に GPU 上で推論が行われます)

2. インストール

仮想環境を作成し、必要なライブラリをインストールします。

# 仮想環境の作成 (例)
python -m venv .venv
source .venv/bin/activate  # Windows の場合は .venv\Scripts\activate

# 依存パッケージのインストール
pip install -r requirements.txt

---

使用方法

画像パスおよびデータベースパスはすべてコマンドライン引数のみで指定します。コード内のハードコーディングは不要です。

1. 画像インデックスの作成・更新 (update_index.py)

検索したい画像が保存されているフォルダをスキャンし、データベースを作成（または更新）します。

python update_index.py --image-dir "/path/to/images" --db-path "/path/to/image_index.db"
# 短縮形
python update_index.py -i "/path/to/images" -d "/path/to/image_index.db"

• --image-dir (-i): 画像が格納されているフォルダパス (サブフォルダも再帰的に検索されます)
• --db-path (-d): 出力される SQLite データベースファイルの保存先パス

2. 検索サーバーの起動 (server.py)

作成されたデータベースを指定して、MCP / HTTP サーバーを起動します。

python server.py --db-path "/path/to/image_index.db"
# 短縮形
python server.py -d "/path/to/image_index.db"

• --db-path (-d): update_index.py で作成した SQLite データベースファイルのパス

起動すると、デフォルトで http://localhost:8000 でサーバーが待機します。

---

Claude Desktop への連携設定

Claude Desktop で本 MCP サーバーを登録して利用するには、claude_desktop_config.json に以下の設定を追加します。

{
  "mcpServers": {
    "local-image-search": {
      "command": "python",
      "args": [
        "C:/absolute/path/to/search-image-mcp/server.py",
        "--db-path",
        "C:/absolute/path/to/search-image-mcp/image_index.db"
      ]
    }
  }
}

(※ パスはすべてご自身の環境の絶対パスに書き換えてください。Windows の場合、パスの区切り文字は / にすることをお勧めします)

---

ライセンス

MIT License