MCP 服务器

Local Image Search (Japanese) MCP Server

Enables searching local images using natural Japanese queries, leveraging a Japanese-specific CLIP model for similarity search and providing efficient caching and fast retrieval via MCP and HTTP endpoints.

README

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"
      ]
    }
  }
}