Gemini Embedding 2 Mcp

---

Google の gemini-embedding-2-preview モデルと、完全にローカルで動作する ChromaDB ベクトルデータベースを使って、ローカルのドキュメント、コード、PDF、画像、音声、動画を Claude、Cursor、VS Code に直接接続できます。

テキストのみを扱うローカル RAG ツールとは異なり、このサーバーはテキスト、PDF のビジュアルページ、画像、音声、動画を単一のローカルメモリレイヤーで管理し、正確なファイルパスとページまたはチャンクのコンテキストをエージェントに返します。

このツールの特長

• モダリティを横断する単一の埋め込み空間：同じメモリレイヤーからコード、PDF、画像、音声、動画を検索できます。
• ローカル優先の永続化：インデックスはホスト型ベクトルデータベースではなく、~/.gemini_mcp_db に保存されます。
• エージェントに適した検索結果：検索結果には正確なパス、タイプ、モダリティ、ページを考慮したコンテキストが含まれます。
• デフォルトで設定不要：組み込みのガードレールと適切なインデックス作成のデフォルト設定により、ほとんどのユーザーは設定ファイルを用意する必要がありません。

できること

• デザイン トークンを説明している PDF のページを見つけてください。
• ダークなサイドバーがあるダッシュボードのスクリーンショットを画像ライブラリから検索してください。
• 価格変更について話した音声または動画のクリップを見つけてください。
• インシデント対応に関するオンボーディングのメモを、仕事用ドキュメントのフォルダーだけから検索してください。
• 検索結果 2 の前後のコンテキストを表示して、元のファイルを正確に引用できるようにしてください。

✨ 主な機能

機能	説明
🧠 統合マルチモーダル検索	テキスト、PDF のビジュアルページ、画像、音声、動画を単一のローカルセマンティックメモリに保存し、1 回のクエリで複数のモダリティを横断して検索できます。
📄 PDF のビジュアル検索	PDF をページごとに画像としてレンダリングして Gemini Embedding 2 に渡す一方、エージェントが読み取れる引用とコンテキストのために抽出したテキストも保持します。
🎯 精度を調整できる検索制御	スコープ、パスのプレフィックス、タイプ、拡張子、モダリティ用のコンパクトなフィルターに対応しており、エージェントは複雑な設定なしで正確に検索できます。
👀 インデックス作成前のプレビュー	preview_directory() は、スキャンを実行する前に、モダリティとスキップ理由ごとにまとめてインデックス作成の対象を表示します。
🧾 コンテキストを考慮した結果	get_result_context() は前後のチャンクまたはページを返すため、検索後にエージェントが正確なソース内容を確認できます。
🛡️ ローカルでのプライバシー保護とガードレール	ローカルの ChromaDB ストアを使用し、既定で不要なフォルダーをスキップし、危険なルートのスキャンをブロックします。また、重複排除と孤立ファイルのクリーンアップも自動的に処理します。

---

🚀 インストールとセットアップ

このサーバーの実行方法は、インストール不要（推奨）と ローカル開発用クローン の 2 通りに対応しています。 お使いのマシンに uv がインストールされていることを確認してください（pip install uv）。

方法 1：インストール不要（推奨）

リポジトリをローカルにクローンせずに、AI アシスタントに GitHub からサーバーを直接実行させることができます。uvx は Python 用の npx のようなもので、セキュアな一時環境にサーバーを自動的にダウンロードしてキャッシュします。

PyPI は、タグ付きリリースの長期的に安定した配布チャネルとして設定されています。最初の PyPI への公開が完了するまでは、以下のリリースタグを指定した Git インストールを使用してください。

安定版のインストールでは、リリースタグを指定します。

uvx --from git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@<release-tag> gemini-embedding-2-mcp

例：

uvx --from git+https://github.com/AlaeddineMessadi/[email protected] gemini-embedding-2-mcp

エッジ版のインストールでは、タグを省略して最新の main ブランチの状態を追跡します。

PyPI への公開が開始された後は、安定版のインストールコマンドは次のようになります。

uvx gemini-embedding-2-mcp-server

🔑 Gemini API キーの取得

埋め込みモデルを動作させるには、Google の無料 API キーが必要です。

1. Google AI Studio にアクセスします。
2. Create API key をクリックします。
3. キーをコピーし、以下のクライアント設定で GEMINI_API_KEY として使用します。

---

🔌 クライアント接続ガイド

🤖 Claude Code（CLI）

このサーバーは Claude Code CLI にネイティブで接続できます。 ターミナルで次のコマンドを実行します。

claude mcp add gemini-embedding-2-mcp \
  --env GEMINI_API_KEY="your-api-key-here" \
  -- uvx --from git+https://github.com/AlaeddineMessadi/[email protected] gemini-embedding-2-mcp

🦋 Claude Desktop

Claude Desktop の設定ファイル（macOS では通常 ~/Library/Application Support/Claude/claude_desktop_config.json）を開き、次を追加します。

{
  "mcpServers": {
    "gemini-embedding-2-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AlaeddineMessadi/[email protected]",
        "gemini-embedding-2-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 Cursor IDE

1. Settings > Features > MCP に移動します。
2. + Add new MCP server をクリックします。
3. タイプとして command を選択します。
4. 名前：gemini-embedding
5. コマンド：GEMINI_API_KEY="your-api-key" uvx --from git+https://github.com/AlaeddineMessadi/[email protected] gemini-embedding-2-mcp

🏄‍♂️ Windsurf（Cascade）

~/.codeium/windsurf/mcp_config.json ファイルを開き、次を追加します。

{
  "mcpServers": {
    "gemini-embedding-2-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AlaeddineMessadi/[email protected]",
        "gemini-embedding-2-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

⚡ Zed Editor

~/.config/zed/settings.json を開き、MCP サーバーのブロックを追加します。

{
  "experimental.mcp": {
    "gemini-embedding-2-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AlaeddineMessadi/[email protected]",
        "gemini-embedding-2-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 VS Code（Cline / RooCode を使用）

~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json を開き、次を追加します。

{
  "mcpServers": {
    "gemini-embedding": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AlaeddineMessadi/[email protected]",
        "gemini-embedding-2-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

---

方法 2：ローカルで開発用にクローン

ソースコードを変更する場合：

# 1. Clone the repository
git clone https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git
cd gemini-embedding-2-mcp-server

# 2. Install dependencies
uv sync

（この方法を使う場合、次を実行してローカルの Claude Code CLI に直接追加できます。）

claude mcp add gemini-embedding-local --env GEMINI_API_KEY="your-api-key" -- uv --directory "$(pwd)" run gemini-embedding-2-mcp

---

方法 3：Docker

レジストリの検証やデプロイ用にコンテナ化された MCP サーバーが必要な場合は、同梱のイメージをビルドして実行します。

docker build -t gemini-embedding-2-mcp-server .
docker run --rm -i \
  -e GEMINI_API_KEY="your-api-key-here" \
  -v "$HOME/.gemini_mcp_db:/root/.gemini_mcp_db" \
  gemini-embedding-2-mcp-server

コンテナは他のローカル MCP サーバーと同様に標準入出力を介して通信し、マウントされたボリュームに ChromaDB データを永続化します。

---

🛠️ 公開される MCP 機能

接続すると、AI アシスタントはすぐに次のツールを利用できるようになります。

⚙️ ツール

• index_directory(path: str, ignore: list = None): 新しいローカルフォルダーをスキャンし、DB に正式に埋め込みます。ワイルドカードの ignore パターンを安全にサポートします。
• preview_directory(path: str, ignore: list = None): スキャンをドライランし、モダリティとスキップ理由ごとに分類して、インデックス登録される内容を確認します。
• search_my_documents(query: str, limit: int, scope: str = None, types: list[str] = None, path_prefix: str = None, extensions: list[str] = None, modalities: list[str] = None): コンパクトな検索フィルターを使って、セマンティック検索を実行します。
• get_result_context(source: str, locator: str = None, window: int = 1): インデックス登録済みの検索結果について、近傍のチャンクまたはページのコンテキストを取得します。
• list_indexed_directories(): AI がすでに把握しているディレクトリのルートを確認します。
• sync_indexed_directories(): DB に新規ファイル、更新ファイル、または最近削除されたファイル（ゴーストファイル）を自動で検出させ、ベクトルをクリーンアップします。
• remove_directory_from_index(path: str): 指定したディレクトリに関連する一連のベクトルを削除します。

🔎 精密なフィルター

メインの検索ツールはデフォルトでシンプルですが、より正確な結果が必要な場合に役立つ、いくつかの高機能なフィルターに対応しています。

• scope：/Users/me/work のような大まかなディレクトリの範囲に一致を限定します
• path_prefix：より詳細なパスのプレフィックスに一致を限定します
• types：text や pdf_visual_page など、保存されているアイテムの種類で絞り込みます
• extensions：.pdf や .md など、ファイル拡張子で絞り込みます
• modalities：text、pdf、image、audio、video などのモダリティで絞り込みます

📊 リソース

• gemini://database-stats：リアルタイムの可観測性を実現します。ChromaDB 内のベクトルセグメントの正確な規模を、アシスタントのコンテキストに直接公開します。

---

📚 技術ドキュメント

• アーキテクチャの詳細
• 究極のマルチモーダル対応と PDF RAG
• エージェントの安全性を確保するガードレール
• ユースケース
• 結果モデル
• リリース

📜 ライセンス

MIT © Alaeddine Messadi