Qdrant MCP Server

公式

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

ドキュメント

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 (string): 保存する情報
  - metadata (JSON): 保存するオプションのメタデータ
  - collection_name (string): 情報を保存するコレクションの名前。デフォルトのコレクション名がない場合、このフィールドは必須です。デフォルトのコレクション名がある場合、このフィールドは有効になりません。
- 戻り値: 確認メッセージ
qdrant-find
- Qdrant データベースから関連情報を取得します
- 入力:
  - query (string): 検索に使用するクエリ
  - collection_name (string): 情報を保存するコレクションの名前。デフォルトのコレクション名がない場合、このフィールドは必須です。デフォルトのコレクション名がある場合、このフィールドは有効になりません。
- 戻り値: 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`	store ツールのカスタム説明	`settings.py` のデフォルトを参照
`TOOL_FIND_DESCRIPTION`	find ツールのカスタム説明	`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] サーバーをすべてのネットワークインターフェースでリッスンさせるために 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 サーバーを設定できます。 MCP サーバーを Cursor に追加する方法の説明は、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 で指定されたツールの説明は、MCP サーバーの使用方法を Claude Code にガイドします。上記のものは例であり、特定のユースケースに合わせてカスタマイズする必要がある場合があります。ただし、 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 ファイルをご覧ください。