Qdrant

公式

Qdrantベクトル検索エンジンの上にセマンティックメモリレイヤーを実装する

GitHub

1.5k

Qdrant MCPで何ができますか？

記憶の保存 — アシスタントにqdrant-storeを使って情報を保存するよう依頼します。オプションでメタデータを含めたり、特定のコレクションを指定したりできます。
セマンティック検索 — qdrant-findを使用して、自然言語クエリで関連する保存済み情報を取得します。結果はQDRANT_SEARCH_LIMITで制限されます。
コードスニペット管理 — ツールの説明を設定して、コードをメタデータ付きで保存し、セマンティック検索で取得してCursorやClaude Codeで再利用できるようにします。
読み取り専用モード — QDRANT_READ_ONLYを有効にすると、qdrant-storeが無効になり、検索操作のみが許可されます。

ドキュメント

mcp-server-qdrant: Qdrant MCPサーバー

Model Context Protocol (MCP) は、LLMアプリケーションと外部データソースおよびツール間のシームレスな統合を可能にするオープンプロトコルです。AIを活用したIDEの構築、チャットインターフェースの拡張、カスタムAIワークフローの作成など、MCPはLLMが必要とするコンテキストに接続するための標準化された方法を提供します。

このリポジトリは、ベクター検索エンジンである Qdrant 用のMCPサーバーを作成する方法の例です。

概要

Qdrantベクター検索エンジンでメモリを保存・取得するための公式Model Context Protocolサーバーです。Qdrantデータベースの上にセマンティックメモリレイヤーとして機能します。

コンポーネント

ツール

qdrant-store
- Qdrantデータベースに情報を保存します
- 入力:
  - information (文字列): 保存する情報
  - metadata (JSON): 保存する任意のメタデータ
  - collection_name (文字列): 情報を保存するコレクションの名前。デフォルトのコレクション名がない場合は必須です。デフォルトのコレクション名がある場合、このフィールドは有効になりません。
- 戻り値: 確認メッセージ
qdrant-find
- Qdrantデータベースから関連情報を取得します
- 入力:
  - query (文字列): 検索に使用するクエリ
  - collection_name (文字列): 情報を保存するコレクションの名前。デフォルトのコレクション名がない場合は必須です。デフォルトのコレクション名がある場合、このフィールドは有効になりません。
- 戻り値: Qdrantデータベースに保存された情報を個別のメッセージとして返します

環境変数

設定は環境変数を介して行われます。唯一のコマンドライン引数は --transport で、トランスポートプロトコルを選択するために使用されます。

[!NOTE] QDRANT_URL と QDRANT_LOCAL_PATH を同時に指定することはできません。

名前	説明	デフォルト値
`QDRANT_URL`	QdrantサーバーのURL	なし
`QDRANT_API_KEY`	QdrantサーバーのAPIキー	なし
`COLLECTION_NAME`	使用するデフォルトコレクションの名前	なし
`QDRANT_LOCAL_PATH`	ローカルQdrantデータベースへのパス（`QDRANT_URL` の代替）	なし
`EMBEDDING_PROVIDER`	使用する埋め込みプロバイダー（現在は "fastembed" のみサポート）	`fastembed`
`EMBEDDING_MODEL`	使用する埋め込みモデルの名前	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	ストアツールのカスタム説明	`settings.py` のデフォルトを参照
`TOOL_FIND_DESCRIPTION`	ファインドツールのカスタム説明	`settings.py` のデフォルトを参照
`QDRANT_SEARCH_LIMIT`	検索から返す最大結果数	`10`
`QDRANT_READ_ONLY`	読み取り専用モードを有効にする（`qdrant-store` ツールを無効化）	`false`

FastMCP環境変数

mcp-server-qdrant はFastMCPに基づいているため、すべてのFastMCP環境変数もサポートしています。最も重要なものを以下に示します:

環境変数	説明	デフォルト値
`FASTMCP_LOG_LEVEL`	ログレベルを設定 (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	デバッグモードを有効にする	`false`
`FASTMCP_SERVER_HOST`	サーバーをバインドするホストアドレス	`127.0.0.1`
`FASTMCP_SERVER_PORT`	サーバーを実行するポート	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	重複リソースの動作 (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	重複ツールの動作 (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	重複プロンプトの動作 (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	サーバー環境にインストールする依存関係のリスト	`[]`

[!NOTE] サーバー固有の設定には FASTMCP_SERVER_ プレフィックスが使用されます。これは将来のバージョンで変更される可能性があります。

インストール

uvxを使用する場合

uvx を使用する場合、mcp-server-qdrant を直接実行するための特定のインストールは必要ありません。

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant

トランスポートプロトコル

サーバーは、--transport フラグを使用して指定できるさまざまなトランスポートプロトコルをサポートしています:

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse

サポートされているトランスポートプロトコル:

stdio (デフォルト): 標準入出力トランスポート。ローカルMCPクライアントでのみ使用可能
sse: Server-Sent Eventsトランスポート。リモートクライアントに最適
streamable-http: Streamable HTTPトランスポート。リモートクライアントに最適。SSEよりも新しい

指定がない場合のデフォルトのトランスポートは stdio です。

SSEトランスポートを使用する場合、サーバーは指定されたポートでリッスンし、着信接続を待ちます。デフォルトのポートは8000ですが、FASTMCP_SERVER_PORT 環境変数を使用して変更できます。

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_PORT=1234 \
uvx mcp-server-qdrant --transport sse

Dockerを使用する場合

MCPサーバーをビルドして実行するためのDockerfileが用意されています:

# Build the container
docker build -t mcp-server-qdrant .

# Run the container
docker run -p 8000:8000 \
  -e FASTMCP_SERVER_HOST="0.0.0.0" \
  -e QDRANT_URL="http://your-qdrant-server:6333" \
  -e QDRANT_API_KEY="your-api-key" \
  -e COLLECTION_NAME="your-collection" \
  mcp-server-qdrant

[!TIP] Dockerコンテナでサーバーを実行する場合、すべてのネットワークインターフェースでリッスンするように FASTMCP_SERVER_HOST="0.0.0.0" を設定していることに注意してください。これはDockerコンテナでサーバーを実行する際に必要です。

Smitheryを使用したインストール

Smithery を介してClaude Desktop用のQdrant MCPサーバーを自動的にインストールするには:

npx @smithery/cli install mcp-server-qdrant --client claude

Claude Desktopの手動設定

このサーバーをClaude Desktopアプリで使用するには、claude_desktop_config.json の "mcpServers" セクションに次の設定を追加してください:

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_URL": "https://xyz-example.eu-central.aws.cloud.qdrant.io:6333",
      "QDRANT_API_KEY": "your_api_key",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

ローカルQdrantモードの場合:

{
  "qdrant": {
    "command": "uvx",
    "args": ["mcp-server-qdrant"],
    "env": {
      "QDRANT_LOCAL_PATH": "/path/to/qdrant/database",
      "COLLECTION_NAME": "your-collection-name",
      "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
    }
  }
}

このMCPサーバーは、指定された名前のコレクションが存在しない場合、自動的に作成します。

デフォルトでは、サーバーは sentence-transformers/all-MiniLM-L6-v2 埋め込みモデルを使用してメモリをエンコードします。現時点では、FastEmbed モデルのみがサポートされています。

他のツールのサポート

このMCPサーバーは、MCP互換の任意のクライアントで使用できます。たとえば、Model Context Protocolの組み込みサポートを提供する Cursor や VS Code で使用できます。

Cursor/Windsurfでの使用

ツールの説明をカスタマイズすることで、このMCPサーバーをCursorまたはWindsurfのコード検索ツールとして設定できます:

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="code-snippets" \
TOOL_STORE_DESCRIPTION="Store reusable code snippets for later retrieval. \
The 'information' parameter should contain a natural language description of what the code does, \
while the actual code should be included in the 'metadata' parameter as a 'code' property. \
The value of 'metadata' is a Python dictionary with strings as keys. \
Use this whenever you generate some code snippet." \
TOOL_FIND_DESCRIPTION="Search for relevant code snippets based on natural language descriptions. \
The 'query' parameter should describe what you're looking for, \
and the tool will return the most relevant code snippets. \
Use this when you need to find existing code snippets for reuse or reference." \
uvx mcp-server-qdrant --transport sse # Enable SSE transport

Cursor/Windsurfでは、SSEトランスポートプロトコルを使用してこの実行中のサーバーをポイントすることで、設定でMCPサーバーを構成できます。CursorにMCPサーバーを追加する方法の説明は、https://docs.cursor.com/context/model-context-protocol#adding-an-mcp-server-to-cursor にあります。Cursor/Windsurfをローカルで実行している場合は、次のURLを使用できます:

http://localhost:8000/sse

[!TIP] Cursor/WindsurfをMCPサーバーに接続するには、リモート接続をサポートできるSSEトランスポートを推奨します。これにより、サーバーをチームと簡単に共有したり、クラウド環境で使用したりできます。

この設定により、Qdrant MCPサーバーは次のことができる特殊なコード検索ツールに変換されます:

コードスニペット、ドキュメント、実装の詳細を保存
セマンティック検索に基づいて関連するコード例を取得
開発者が特定の実装や使用パターンを見つけるのを支援

コードスニペットの自然言語による説明（information パラメータ）と実際のコード（metadata.code プロパティ）を保存してデータベースを投入し、探しているものを説明する自然言語クエリで検索できます。

[!NOTE] 上記のツールの説明は例であり、特定のユースケースに合わせてカスタマイズする必要がある場合があります。チームのワークフローや保存・取得したいコードスニペットの種類に合わせて説明を調整することを検討してください。

mcp-server-qdrant が正常にインストールされているのにCursorで動作しない場合は、エージェントが新しいコードスニペットを生成するときにMCPツールが常に使用されるように Cursorルールを作成することを検討してください。特定のファイルタイプに対してのみルールを制限して、ドキュメントや他のタイプのコンテンツにMCPサーバーを使用しないようにできます。

Claude Codeでの使用

このMCPサーバーに接続してClaude Codeの機能を拡張し、既存のコードベースに対するセマンティック検索を有効にできます。

mcp-server-qdrantのセットアップ

MCPサーバーをClaude Codeに追加:

# Add mcp-server-qdrant configured for code search
claude mcp add code-search \
-e QDRANT_URL="http://localhost:6333" \
-e COLLECTION_NAME="code-repository" \
-e EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
-e TOOL_STORE_DESCRIPTION="Store code snippets with descriptions. The 'information' parameter should contain a natural language description of what the code does, while the actual code should be included in the 'metadata' parameter as a 'code' property." \
-e TOOL_FIND_DESCRIPTION="Search for relevant code snippets using natural language. The 'query' parameter should describe the functionality you're looking for." \
-- uvx mcp-server-qdrant

サーバーが追加されたことを確認:
```
claude mcp list
```

Claude Codeでのセマンティックコード検索の使用

TOOL_STORE_DESCRIPTION と TOOL_FIND_DESCRIPTION で指定されたツールの説明は、Claude CodeにMCPサーバーの使用方法を指示します。上記のものは例であり、特定のユースケースに合わせてカスタマイズする必要がある場合があります。ただし、Claude Codeはすでに次のことができるはずです:

qdrant-store ツールを使用して、説明付きのコードスニペットを保存する。
qdrant-find ツールを使用して、自然言語で関連するコードスニペットを検索する。

開発モードでMCPサーバーを実行

MCPサーバーは、mcp dev コマンドを使用して開発モードで実行できます。これによりサーバーが起動し、ブラウザでMCPインスペクターが開きます。

COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

VS Codeでの使用

ワンクリックインストールの場合は、以下のインストールボタンのいずれかをクリックしてください:

手動インストール

VS Codeのユーザー設定（JSON）ファイルに次のJSONブロックを追加してください。これを行うには、Ctrl + Shift + P を押して Preferences: Open User Settings (JSON) と入力します。

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "uvx",
        "args": ["mcp-server-qdrant"],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

または、Dockerを使用する場合は、代わりに次の設定を追加してください:

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "qdrantUrl",
        "description": "Qdrant URL"
      },
      {
        "type": "promptString",
        "id": "qdrantApiKey",
        "description": "Qdrant API Key",
        "password": true
      },
      {
        "type": "promptString",
        "id": "collectionName",
        "description": "Collection Name"
      }
    ],
    "servers": {
      "qdrant": {
        "command": "docker",
        "args": [
          "run",
          "-p", "8000:8000",
          "-i",
          "--rm",
          "-e", "QDRANT_URL",
          "-e", "QDRANT_API_KEY",
          "-e", "COLLECTION_NAME",
          "mcp-server-qdrant"
        ],
        "env": {
          "QDRANT_URL": "${input:qdrantUrl}",
          "QDRANT_API_KEY": "${input:qdrantApiKey}",
          "COLLECTION_NAME": "${input:collectionName}"
        }
      }
    }
  }
}

別の方法として、ワークスペースに次の内容の .vscode/mcp.json ファイルを作成することもできます:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "uvx",
      "args": ["mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

Dockerを使用したワークスペース設定では、.vscode/mcp.json で次を使用します:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qdrantUrl",
      "description": "Qdrant URL"
    },
    {
      "type": "promptString",
      "id": "qdrantApiKey",
      "description": "Qdrant API Key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "collectionName",
      "description": "Collection Name"
    }
  ],
  "servers": {
    "qdrant": {
      "command": "docker",
      "args": [
        "run",
        "-p", "8000:8000",
        "-i",
        "--rm",
        "-e", "QDRANT_URL",
        "-e", "QDRANT_API_KEY",
        "-e", "COLLECTION_NAME",
        "mcp-server-qdrant"
      ],
      "env": {
        "QDRANT_URL": "${input:qdrantUrl}",
        "QDRANT_API_KEY": "${input:qdrantApiKey}",
        "COLLECTION_NAME": "${input:collectionName}"
      }
    }
  }
}

コントリビューション

mcp-server-qdrantの改善について提案がある場合、またはバグを報告したい場合は、issueを開いてください！あらゆるコントリビューションを歓迎します。

`mcp-server-qdrant` をローカルでテスト

MCPインスペクターは、MCPサーバーをテストおよびデバッグするための開発者ツールです。クライアントUI（デフォルトポート5173）とMCPプロキシサーバー（デフォルトポート3000）の両方を実行します。ブラウザでクライアントUIを開いてインスペクターを使用します。

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

起動したら、ブラウザで http://localhost:5173 を開いてインスペクターインターフェースにアクセスします。

ライセンス

このMCPサーバーはApache License 2.0の下でライセンスされています。つまり、Apache License 2.0の条項および条件に従って、ソフトウェアを自由に使用、変更、配布することができます。詳細については、プロジェクトリポジトリ内のLICENSEファイルを参照してください。