Qdrant MCPサーバーでClaudeにベクトル検索の記憶を持たせる手順

Qdrant MCPサーバーとは

Qdrant MCPサーバー(mcp-server-qdrant)は、ベクトル検索エンジンQdrantをClaudeから使えるようにするMCPサーバーです。Qdrant自身が公開しているリポジトリで、READMEは「Qdrantに記憶を保存し、取り出すための公式MCPサーバー」と位置づけています。Qdrantの上に意味検索つきの記憶層を載せる、という役割です。

使い道は2つに分かれます。

会話で出た決定事項や好みを保存し、次のセッションで思い出させる記憶
書いたコード片を説明文つきで保存し、自然文で探し直すコード検索

どちらも同じ2つのツールで動きます。違うのは、ツールの説明文とコレクションの使い方だけです。接続の手間は、Exaのようなホスト型サーバーより大きくなります。Qdrant本体を自分で用意し、uvxが動く環境を整える必要があるためです。

2つのツールが何をするか

サーバーが公開するツールはqdrant-storeとqdrant-findの2つだけです。

ツール	役割	主な入力
`qdrant-store`	役割情報をQdrantに保存する	主な入力`information`(文字列)、`metadata`(任意のJSON)、`collection_name`
`qdrant-find`	役割クエリに近い情報を取り出す	主な入力`query`(文字列)、`collection_name`

collection_nameは、既定のコレクション名を環境変数で決めていないときだけ必須です。既定を決めた場合、この引数はツール側で無効になります。つまりClaudeに保存先を選ばせたくないなら、COLLECTION_NAMEを必ず設定しておきます。

qdrant-findは見つけた情報を、複数のメッセージに分けて返します。1件ずつ別のメッセージになるため、Claudeは上位の結果をそのまま文脈として読めます。

事前に必要なもの

uvxを使う起動方法が基本です。READMEによると、uvxで動かす場合は事前のインストール作業は要りません。PyPIのパッケージ情報では、バージョンは0.8.1、対応するPythonは3.10以上です。依存にはFastEmbed、FastMCP、qdrant-clientが並んでいます。

接続先のQdrantは、次のどちらかを選びます。

Qdrantサーバー(ローカルのDockerやQdrant Cloud)をQDRANT_URLで指す
ローカルのデータベースをQDRANT_LOCAL_PATHのパスで指す

この2つは同時に指定できません。両方を渡すと設定として成立しない、とREADMEに書かれています。

環境変数の早見表

設定はすべて環境変数で行います。コマンドライン引数は--transportだけです。

変数	意味	既定値
`QDRANT_URL`	意味QdrantサーバーのURL	既定値なし
`QDRANT_API_KEY`	意味QdrantサーバーのAPIキー	既定値なし
`QDRANT_LOCAL_PATH`	意味ローカルDBのパス(`QDRANT_URL`の代替)	既定値なし
`COLLECTION_NAME`	意味既定のコレクション名	既定値なし
`EMBEDDING_MODEL`	意味埋め込みモデル名	既定値`sentence-transformers/all-MiniLM-L6-v2`
`QDRANT_SEARCH_LIMIT`	意味検索で返す最大件数	既定値10
`QDRANT_READ_ONLY`	意味読み取り専用にし`qdrant-store`を無効化	既定値false
`TOOL_STORE_DESCRIPTION` / `TOOL_FIND_DESCRIPTION`	意味各ツールの説明文を差し替える	既定値settings.pyの既定文

EMBEDDING_PROVIDERという変数もありますが、現状で使える値はfastembedだけで、これが既定です。モデルもFastEmbedが扱えるものに限られます。指定したコレクションが無ければ、サーバーが自動で作ります。

Claude Codeに接続する

Claude Codeではclaude mcp addで追加します。stdioサーバーなので、--より後ろがサーバーを起動するコマンドになります。次はREADMEのコード検索用の例から、接続に必要な設定だけを残した最小構成です。

claude mcp add qdrant \
  -e QDRANT_URL="http://localhost:6333" \
  -e COLLECTION_NAME="claude-memory" \
  -- uvx mcp-server-qdrant

追加できたかはclaude mcp listで見ます。Claude Codeのドキュメントによると、一覧には各サーバーの接続状態が出ます。

3つのスコープと保存先

claude mcp addは、何も付けなければローカルスコープに書き込みます。どこに保存され、誰と共有されるかは、スコープごとに違います。

スコープ	有効な範囲	チームと共有	保存先
local(既定)	有効な範囲追加したプロジェクトだけ	チームと共有されない	保存先`~/.claude.json`
project(`--scope project`)	有効な範囲そのプロジェクトだけ	チームと共有バージョン管理で共有	保存先プロジェクト直下の`.mcp.json`
user(`--scope user`)	有効な範囲自分の全プロジェクト	チームと共有されない	保存先`~/.claude.json`

同じ名前のサーバーが複数のスコープにあるときは、local、project、userの順に優先されます。同じ名前で接続先の違う定義を複数のスコープに置くと、claude mcp listと/mcpに衝突の警告が出ます。不要な定義はclaude mcp remove <name> --scope <scope>で消せます。Qdrantの接続先が個人用ならlocalかuser、チームで同じコレクションを引くならprojectが合います。

設定ファイルに何が書かれるか

空の設定ディレクトリを使い、一時フォルダで--scope projectを付けて実行すると、書き込まれる内容を確かめられます(Claude Code v2.1.295)。

claude mcp add qdrant --scope project \
  -e QDRANT_URL=http://localhost:6333 \
  -e COLLECTION_NAME=claude-memory \
  -- uvx mcp-server-qdrant

プロジェクト直下に作られた.mcp.jsonは、次のとおりでした。

{
  "mcpServers": {
    "qdrant": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "COLLECTION_NAME": "claude-memory"
      }
    }
  }
}

この状態でclaude mcp listを実行すると、qdrant: uvx mcp-server-qdrant - ⏸ Pending approvalと表示されました。プロジェクトスコープのサーバーは、対話セッションで承認するまで接続されません。チームで共有する設定は、承認の手順を1回挟む前提で配ります。

APIキーを.mcp.jsonに書かない

Qdrant Cloudを使うとQDRANT_API_KEYが必要になります。--scope projectでキーを直接渡すと、.mcp.jsonにそのまま書かれ、コミットすればリポジトリに残ります。

回避策は2つあります。1つは既定のローカルスコープを使うことです。ローカルスコープの設定は~/.claude.jsonに保存され、そのプロジェクトだけで有効で、自分だけに見えます。もう1つは、.mcp.jsonのenvで${QDRANT_API_KEY}と書き、値をシェルの環境変数から展開する方法です。${VAR}と${VAR:-default}の2つの書式が使えます。

"env": {
  "QDRANT_URL": "${QDRANT_URL:-http://localhost:6333}",
  "QDRANT_API_KEY": "${QDRANT_API_KEY}",
  "COLLECTION_NAME": "claude-memory"
}

stdioサーバーへ渡す環境変数の範囲を絞りたい場合は、CLAUDE_CODE_MCP_ALLOWLIST_ENVの記事に挙動をまとめています。

Claude Desktopに接続する

Claude Desktopには2つの入れ方があります。

1つ目は、Smitheryを使う自動インストールです。READMEのコマンドは次の1行です。

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

2つ目は、claude_desktop_config.jsonのmcpServersに手で追記する方法です。READMEのスニペットは、mcpServersの中に入れるqdrantの部分だけを載せています。下の例は、外側にmcpServersを足した完成形です。

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

ローカルDBで済ませるなら、QDRANT_URLとQDRANT_API_KEYの代わりにQDRANT_LOCAL_PATHを置きます。サーバーを立てずに試せる分、最初の動作確認には向いています。ただしQDRANT_URLとの併用はできません。READMEのローカル用の設定は次の形で、EMBEDDING_MODELには既定値と同じモデルを明記しています。

{
  "mcpServers": {
    "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"
      }
    }
  }
}

/path/to/qdrant/databaseは、データベースを置きたい実際のパスに書き換えます。

記憶として使うための設計

サーバーを繋いだだけでは、Claudeが勝手に保存し、勝手に思い出すわけではありません。いつqdrant-storeを呼ぶかは、ツールの説明文とプロジェクトの指示で決まります。

READMEは、コード検索用にTOOL_STORE_DESCRIPTIONとTOOL_FIND_DESCRIPTIONを書き換える例を載せています。説明文で「informationには何をするコードかの自然文、metadataのcodeプロパティにコード本体を入れる」と指示する形です。READMEのコード検索用コマンドは、次のとおりです。

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に教える役目を持っています。記憶では、保存するものが「判断の要約」と「その理由」に変わります。そこで説明文だけを入れ替えたのが次の例です(記憶用の文面はこの記事のための例で、READMEの引用ではありません)。

claude mcp add qdrant \
  -e QDRANT_URL="http://localhost:6333" \
  -e COLLECTION_NAME="claude-memory" \
  -e TOOL_STORE_DESCRIPTION="Store a decision or preference the user wants to keep. Put a one-sentence summary in 'information' and the reason in 'metadata.reason'." \
  -e TOOL_FIND_DESCRIPTION="Search stored decisions and preferences. Use it before proposing a design that may conflict with a past decision." \
  -- uvx mcp-server-qdrant

説明文だけで足りない場合は、CLAUDE.mdにも書いておきます。READMEもCursorで動かないときの対策として、ルールでツールを常に使わせる方法を挙げています。Claude Codeでの例です。

## 記憶(qdrant)
- 設計判断を確定したら、要約を qdrant-store で保存する
- 新しい設計を提案する前に、qdrant-find で過去の判断を検索する
- 保存するのは判断と理由だけ。APIキーや個人情報は保存しない

最後の1行が要点です。保存した内容はQdrantのコレクションに残り、qdrant-findで別のセッションにも出てきます。何でも保存させると、検索結果にノイズが混ざります。

読み取り専用で使う

共有のコレクションを参照だけしたい場合は、QDRANT_READ_ONLY=trueを設定します。qdrant-storeツールが無効になり、Claudeからは検索しかできなくなります。誰かが整備したナレッジを複数人で引くときに、誤って上書きされない構成です。

claude mcp add qdrant-readonly \
  -e QDRANT_URL="https://your-cluster.example:6333" \
  -e QDRANT_API_KEY="$QDRANT_API_KEY" \
  -e COLLECTION_NAME="team-knowledge" \
  -e QDRANT_READ_ONLY="true" \
  -- uvx mcp-server-qdrant

トランスポートの選び方

既定のトランスポートはstdioで、同じマシン上のクライアントから使う前提です。READMEは他にsseとstreamable-httpを挙げ、どちらもリモートのクライアント向けとしています。streamable-httpはSSEより新しい方式だと、READMEは説明しています。

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

待ち受けのポートは8000が既定で、FASTMCP_SERVER_PORTで変えられます。Dockerで動かす場合は、コンテナの外から届くようにFASTMCP_SERVER_HOSTを0.0.0.0にします。READMEが示すビルドと起動のコマンドは次のとおりです。

# リポジトリ直下でイメージをビルド
docker build -t mcp-server-qdrant .
 
# 起動(ポート8000を公開)
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

0.0.0.0はすべてのネットワークインターフェースで待ち受ける指定で、コンテナ内で動かすときに要ります。

つまずきやすい点

接続状態が失敗になる: claude mcp listで失敗の詳細が出ます。QDRANT_URLの到達性と、uvxがPATHにあるかを先に見ます。再接続は/mcpの画面から行えます
保存先が選べない、または選ばれてしまう: COLLECTION_NAMEを設定するとcollection_name引数が消えます。複数コレクションを使い分けたいなら、設定せずにClaudeへ指定させるか、サーバーを2つ登録します
検索結果が多すぎる: QDRANT_SEARCH_LIMITで上限を下げられます。既定は10件です
起動に時間がかかる: Claude CodeはMCP_TIMEOUTでサーバーの起動待ち時間を調整できます。例はMCP_TIMEOUT=10000 claudeです

どこから試すか

最初は、ローカルのQdrantとコレクション1つで、記憶用のツール説明文を試すのが手数の少ない入口です。使い心地が掴めたら、CLAUDE.mdで保存と検索のタイミングを固めます。チームで共有するなら、.mcp.jsonにAPIキーを書かない形と、読み取り専用の設定を先に決めておきます。

ほかのMCPサーバーとの組み合わせでは、パッケージレジストリMCPのように検索結果を返す系のサーバーと、記憶を保存するQdrantを並べて使うと、役割の違いが分かりやすくなります。接続に失敗したときの対処は、/mcp reconnect allの記事が参考になります。

Qdrant MCPサーバーでClaudeにベクトル検索の記憶を持たせる手順

Qdrant MCPサーバーとは

2つのツールが何をするか

事前に必要なもの

環境変数の早見表

Claude Codeに接続する

3つのスコープと保存先

設定ファイルに何が書かれるか

APIキーを.mcp.jsonに書かない

Claude Desktopに接続する

記憶として使うための設計

読み取り専用で使う

トランスポートの選び方

つまずきやすい点

どこから試すか

Claude Codeとは — できること・料金・始め方と使い方の全体像

ClaudeからNeo4j MCPサーバーでグラフDBに問い合わせる手順

Claude CodeでHostinger MCPを使い、ドメインとDNSを管理する

Atlassian Rovo MCPをClaude Codeにつなぐ設定手順と認証の選び方

Statsig MCPサーバーでフラグと実験をClaude Codeから操作する

PostHog MCPサーバーの使い方 — Claude Codeへの接続とCLIモードの仕組み

Qdrant MCPサーバーとは

2つのツールが何をするか

事前に必要なもの

環境変数の早見表

Claude Codeに接続する

3つのスコープと保存先

設定ファイルに何が書かれるか

APIキーを.mcp.jsonに書かない

Claude Desktopに接続する

記憶として使うための設計

読み取り専用で使う

トランスポートの選び方

つまずきやすい点

どこから試すか

関連する記事

Claude Codeとは — できること・料金・始め方と使い方の全体像

ClaudeからNeo4j MCPサーバーでグラフDBに問い合わせる手順

Claude CodeでHostinger MCPを使い、ドメインとDNSを管理する

Atlassian Rovo MCPをClaude Codeにつなぐ設定手順と認証の選び方

Statsig MCPサーバーでフラグと実験をClaude Codeから操作する

PostHog MCPサーバーの使い方 — Claude Codeへの接続とCLIモードの仕組み