mcp-server-qdrant: A Qdrant MCP server

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

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

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

概要

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

コンポーネント

ツール

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

環境変数

設定は環境変数を使って行います。コマンドライン引数は、トランスポートプロトコルを選択するための --transport のみです。

メモ

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

名前	説明	デフォルト値
QDRANT_URL	Qdrant サーバーの URL	None
QDRANT_API_KEY	Qdrant サーバーの API キー	None
COLLECTION_NAME	使用するデフォルトのコレクション名	None
QDRANT_LOCAL_PATH	ローカルの Qdrant データベースへのパス（QDRANT_URL の代替）	None
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	サーバー環境にインストールする依存関係のリスト	[]

メモ

サーバー固有の設定には 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：ストリーム可能な 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

ヒント

サーバーがすべてのネットワークインターフェースで待ち受けるように、FASTMCP_SERVER_HOST="0.0.0.0" を設定しています。これは、Docker コンテナー内でサーバーを実行する際に必要です。

Smithery 経由でのインストール

Smithery 経由で Qdrant MCP Server を Claude Desktop に自動インストールするには、次のようにします。

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 サーバーを追加する方法については、Cursor のドキュメントをご覧ください。Cursor／Windsurf をローカルで実行している場合は、次の URL を使用できます。

http://localhost:8000/sse

ヒント

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

この設定により、Qdrant MCP サーバーは次のことができる、コード検索に特化したツールになります。

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

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

メモ

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

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

Claude Code での使用

この MCP サーバーに接続すると、既存のコードベースをセマンティック検索できるようになり、Claude Code の機能を強化できます。

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

1. Claude Code に MCP サーバーを追加します。

   # コード検索用に設定した mcp-server-qdrant を追加
   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
   

2. サーバーが追加されたことを確認します。

   claude mcp list
   

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

TOOL_STORE_DESCRIPTION と TOOL_FIND_DESCRIPTION で指定するツールの説明は、MCP サーバーの使い方を Claude Code に伝えます。上記は例であり、ユースケースに応じてカスタマイズが必要な場合があります。ただし、Claude Code はすでに次のことができます。

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

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

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

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

VS Code での使用

ワンクリックでインストールするには、以下のインストールボタンのいずれかをクリックしてください。

手動インストール

以下の JSON ブロックを、VS Code の User Settings (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 inspector は、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 ファイルをご覧ください。

プライバシーとサポート

• プライバシーポリシー
• サポート