---
title: "Qdrant MCPの使い方：mcp-server-qdrantをClaude Codeにつなぐ設定と記憶ストア化【v0.8.1対応】"
url: "https://www.issoh.co.jp/tech/details/19491/"
published: 2026-11-08
updated: 2026-11-08
categories: ["データベース"]
publisher: "株式会社一創"
---

# Qdrant MCPの使い方：mcp-server-qdrantをClaude Codeにつなぐ設定と記憶ストア化【v0.8.1対応】

Qdrant MCPは、AIエージェントがQdrantに情報を保存し、意味の近さで呼び出せるようにするMCPサーバーです。この記事では、Qdrant公式の3種類のMCPサーバーの違いを整理したうえで、記憶用のOSS版mcp-server-qdrant（2026年11月8日時点の最新は0.8.1）をuvxで起動し、Claude Codeへ登録する手順を示します。日本語の記憶を引くための埋め込みモデルの選び方、既存の社内文書を同じ形式で投入するPythonコード、削除ツールが無い記憶の消し方まで、公式ドキュメントとソースコードの記述に沿って進めます。

## まとめ：Qdrant MCPは3種類から用途で選び、記憶用はモデルを先に決める

コレクションにデータを保存・検索したいなら、選ぶのはOSS版の`mcp-server-qdrant`です。Qdrant Cloud MCPはクラスタ管理、Docs MCPは公式ドキュメント検索の用途で、どちらもコレクションのデータには触れません。OSS版は`uvx mcp-server-qdrant`で起動し、`claude mcp add`か`.mcp.json`で環境変数を渡して登録します。

最初に決めるべきは埋め込みモデルです。既定の`all-MiniLM-L6-v2`は英語向けのため、日本語の記憶を扱うなら多言語モデルを指定してからデータを入れます。モデルを後から変えると既存の記憶は検索に使えません。削除ツールも無いので、古い記憶はREST APIで消す前提で、プロジェクト単位にコレクションを分けて運用します。

## 公式Qdrant MCP 3種類の役割とOSS版・Cloud MCPの選び分け

「Qdrant MCP」で探すと、役割の違う3つの公式サーバーが見つかります。取り違えると、記憶を保存したいのにクラスタ管理用のサーバーをつないでしまう、といった遠回りになるため、役割の区別が必要です。MCPそのものの仕組みは[MCP（Model Context Protocol）とは？仕組み・APIとの違い・MCPサーバーの作り方](https://www.issoh.co.jp/tech/details/5736/)で解説しているので、ここではQdrant固有の部分に絞ります。

### OSS版の2ツールqdrant-store・qdrant-findと保存形式

[公式のQdrant MCP (Open Source)](https://qdrant.tech/documentation/qdrant-mcp/oss/)によると、OSS版はQdrantのコレクションの上に意味検索の記憶層を作るサーバーです。ツールは2つだけです。`qdrant-store`は文字列の`information`と任意のJSON`metadata`を保存し、`qdrant-find`は自然言語の`query`で近い情報を探して返します。

保存の中身は[v0.8.1のqdrant.py](https://github.com/qdrant/mcp-server-qdrant/blob/v0.8.1/src/mcp%5Fserver%5Fqdrant/qdrant.py)で確認できます。ポイントのIDはUUIDで自動採番され、ペイロードには本文が`document`、付随情報が`metadata`というキーで入ります。埋め込みはサーバー内のFastEmbedで計算するため、OpenAIなど外部の埋め込みAPIのキーは要りません。コレクションが無ければ初回の保存時に自動で作られます。

### Cloud MCPとDocs MCPがデータを読み書きしない理由と使い道

[Qdrant Cloud MCP](https://qdrant.tech/documentation/qdrant-mcp/cloud/)は`https://api.cloud.qdrant.io/mcp`で提供されるリモートサーバーで、OAuthでログインし、クラスタの作成・停止、バックアップ、請求の確認などを会話で行います。公式は、このサーバーはインフラ管理専用でコレクションやポイントは読み書きできないと明記しています。[Qdrant Docs MCP](https://qdrant.tech/documentation/qdrant-mcp/docs/)は`https://search.qdrant.tech/mcp`で、認証なしで公式ドキュメントやブログを検索するためのものです。

| 種類                     | 扱う対象           | 接続方式              | 向いている場面           |
| ---------------------- | -------------- | ----------------- | ----------------- |
| mcp-server-qdrant（OSS） | コレクションのデータ     | uvxでローカル起動（stdio） | エージェントの記憶・社内知識の検索 |
| Qdrant Cloud MCP       | クラスタ・バックアップ・請求 | リモート（HTTP・OAuth）  | Qdrant Cloudの運用作業 |
| Qdrant Docs MCP        | 公式ドキュメント・ブログ   | リモート（HTTP・認証なし）   | 実装中に最新仕様を確かめる     |

この記事の対象はOSS版です。Cloud MCPとDocs MCPは記憶の保存先にはならず、OSS版と併用する補助として位置づけます。

## mcp-server-qdrantをuvxで起動しClaude Codeへ登録する接続手順

ここからは、ローカルのQdrantにOSS版をつなぎ、Claude Codeから使える状態にします。登録の方法は、自分だけで使うなら`claude mcp add`、チームで同じ設定を共有するなら`.mcp.json`が手早い選択です。

### 接続先のQdrantとPython 3.10以上・uvを先に用意する前提条件

接続先のQdrantは、手元なら[Qdrant Dockerの構築手順](https://www.issoh.co.jp/tech/details/19488/)、マネージド版なら[Qdrant Cloudの使い方](https://www.issoh.co.jp/tech/details/19490/)の手順で用意します。[PyPIのmcp-server-qdrant](https://pypi.org/project/mcp-server-qdrant/)はPython 3.10以上が必要です。

注意したいのは依存の固定です。[v0.8.1のpyproject.toml](https://github.com/qdrant/mcp-server-qdrant/blob/v0.8.1/pyproject.toml)は`fastmcp==2.7.0`と`pydantic<2.12.0`を指定しており、PyPIのfastmcpが4.1系まで進んだ現在、アプリと同じ仮想環境に入れると衝突しやすくなります。`uvx`はツールごとに隔離した環境で動かすので、この固定の影響を受けません。`qdrant-client`は1.12.0以上の指定なので、uvxでは最新の1.20系が入り、v1.20系のQdrantサーバーと版が揃います。

### claude mcp addで環境変数を渡して登録し一覧で確かめる手順

[Claude CodeのMCPドキュメント](https://code.claude.com/docs/en/mcp)では、`--`より前がClaude Code側のオプション、後ろがサーバーの起動コマンドと定められています。次の例は、版を0.8.1に固定し、日本語に対応した埋め込みモデルを指定して登録するものです。

```
# 接続確認：Qdrantが応答するか（200なら準備完了）
curl -i http://localhost:6333/readyz

# 自分だけが使う設定として登録する（既定のスコープはlocal）
claude mcp add --transport stdio qdrant-memory \
  -e QDRANT_URL="http://localhost:6333" \
  -e QDRANT_API_KEY="${QDRANT_API_KEY}" \
  -e COLLECTION_NAME="team-memory" \
  -e EMBEDDING_MODEL="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2" \
  -- uvx --from "mcp-server-qdrant==0.8.1" mcp-server-qdrant

# 登録できたか確かめる
claude mcp list
```

`COLLECTION_NAME`を指定すると、ツールの引数から`collection_name`が消え、エージェントは常にこのコレクションへ保存します。指定しない場合はエージェントが毎回コレクション名を決めるため、名前の揺れでデータが散らばりやすい状態です。FastEmbedは初回起動時にモデルを取得するので、起動に時間がかかって接続に失敗する場合は`MCP_TIMEOUT=10000 claude`のように起動待ちの時間を延ばします。

### .mcp.jsonでチーム共有しAPIキーを環境変数の展開で渡す書き方

同じドキュメントによると、`--scope project`で登録した設定はプロジェクト直下の`.mcp.json`に保存され、バージョン管理で共有できます。`env`などの値には`${VAR}`や`${VAR:-default}`の形で環境変数を書けるため、APIキーをファイルに直接書かずに済みます。

```
{
  "mcpServers": {
    "qdrant-memory": {
      "command": "uvx",
      "args": ["--from", "mcp-server-qdrant==0.8.1", "mcp-server-qdrant"],
      "env": {
        "QDRANT_URL": "${QDRANT_URL:-http://localhost:6333}",
        "QDRANT_API_KEY": "${QDRANT_API_KEY}",
        "COLLECTION_NAME": "team-memory",
        "EMBEDDING_MODEL": "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
        "QDRANT_SEARCH_LIMIT": "5"
      }
    }
  }
}
```

環境変数が未設定のまま起動すると、値は`${QDRANT_API_KEY}`という文字列のまま渡され、`claude mcp list`に警告が出ます。`QDRANT_SEARCH_LIMIT`は`qdrant-find`が返す件数の上限で、既定は10です。返す件数が多いほど会話のコンテキストを消費するので、記憶用途では5件前後に絞るのが扱いやすい設定です。

## 日本語の記憶を正しく引くための埋め込みモデルとコレクション設計

接続できても、検索結果が的外れでは記憶ストアとして使えません。OSS版で精度と互換性を左右するのは、埋め込みモデルの選択と、自動作成されるコレクションの形です。ベクトルの基礎は[Pythonでembeddingを生成する方法](https://www.issoh.co.jp/tech/details/4081/)を参照してください。

### 既定のall-MiniLM-L6-v2が英語向けである点と多言語モデルの選択肢

OSS版が使える埋め込みはFastEmbedのモデルだけです。[FastEmbedのSupported Models](https://qdrant.github.io/fastembed/examples/Supported%5FModels/)では、既定の`sentence-transformers/all-MiniLM-L6-v2`は英語向けの384次元と記載されています。日本語の会話や社内文書を記憶させるなら、多言語と表記されたモデルから選びます。

| モデルの略称                | 次元   | 選ぶ場面             |
| --------------------- | ---- | ---------------- |
| 多言語MiniLM-L12         | 384  | 開発機で軽く動かしたい記憶用途  |
| 多言語mpnet-base         | 768  | 精度を上げたいが計算量は抑えたい |
| multilingual-e5-large | 1024 | 社内文書の検索精度を優先する   |

`EMBEDDING_MODEL`に書く正式名は、上から順に`sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`、`sentence-transformers/paraphrase-multilingual-mpnet-base-v2`、`intfloat/multilingual-e5-large`です。次元が大きいほど1件あたりの計算とメモリは増えます。埋め込みはMCPサーバーを動かす各開発者の端末で計算されるため、まずは384次元のモデルで始め、検索の外れが目立つときに大きいモデルの新しいコレクションへ移る順番が無難です。

### 名前付きベクトルfast-とCosine固定が既存コレクションと噛み合わない理由

v0.8.1のqdrant.pyを読むと、自動作成されるコレクションは名前付きベクトルで、名前は`fast-`にモデル名の末尾を小文字にしたもの（既定なら`fast-all-minilm-l6-v2`）、距離はCosineに固定されています。保存も検索もこの名前を指定して行う作りです。

そのため、Pythonクライアントで無名のベクトルとして作った既存コレクションや、別のモデルで作ったコレクションを`COLLECTION_NAME`に指定しても、ベクトル名が合わず使えません。公式のOSSページも、既存コレクションで`EMBEDDING_MODEL`を変えても既存データは埋め込み直されないので、モデルを変えるなら新しいコレクションを使うよう書いています。MCP用のコレクションは、アプリが使うRAG用のコレクションとは分けて作るのが安全です。

### 既存の社内文書をMCPと同じ形式でまとめて投入するPythonコード

エージェントに最初から知識を持たせたい場合、`qdrant-store`を1件ずつ呼ばせるより、同じ形式でまとめて書き込むほうが早く済みます。次のコードは、ベクトル名とペイロードの形をv0.8.1の実装に合わせ、MCPから検索できる状態で投入するものです。

```
# pip install "qdrant-client==1.20.0" "fastembed==0.9.1"
import os
import uuid

from fastembed import TextEmbedding
from qdrant_client import QdrantClient, models

MODEL = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
VECTOR_NAME = "fast-" + MODEL.split("/")[-1].lower()  # MCPサーバーと同じ命名規則
COL = "team-memory"

client = QdrantClient(url="http://localhost:6333", api_key=os.environ.get("QDRANT_API_KEY"))
embedder = TextEmbedding(MODEL)

if not client.collection_exists(COL):
    client.create_collection(
        collection_name=COL,
        vectors_config={VECTOR_NAME: models.VectorParams(size=384, distance=models.Distance.COSINE)},
    )

docs = [
    ("請求書の締め日は毎月25日で、翌月10日に送付する", {"project": "billing", "kind": "rule"}),
    ("本番DBへの手動クエリは承認チケットの番号を残してから実行する", {"project": "ops", "kind": "rule"}),
]
vectors = list(embedder.passage_embed([text for text, _ in docs]))

client.upsert(
    collection_name=COL,
    wait=True,
    points=[
        models.PointStruct(
            id=uuid.uuid4().hex,
            vector={VECTOR_NAME: vec.tolist()},
            payload={"document": text, "metadata": meta},  # MCPのqdrant-findが読むキー
        )
        for (text, meta), vec in zip(docs, vectors)
    ],
)
print(client.count(COL, exact=True).count)
```

文書には`passage_embed`を使います。MCPサーバー側も保存時は`passage_embed`、検索時は`query_embed`で計算しているため、投入側を揃えておくと検索結果の並びがずれません。`metadata`に入れたプロジェクト名は、後述する削除の絞り込みにも使えます。

## AIエージェントの記憶ストアとして運用するときの権限・削除・公開範囲

記憶ストアは、入れた情報がエージェントの次の判断に混ざる仕組みです。何を保存させ、誰が書き込めて、不要になった記憶をどう消すかを、使い始める前に決めておきます。

### 既定のツール説明文にある個人情報の文言を業務向けに書き換える理由

[v0.8.1のsettings.py](https://github.com/qdrant/mcp-server-qdrant/blob/v0.8.1/src/mcp%5Fserver%5Fqdrant/settings.py)にある`qdrant-find`の既定の説明文には、使う場面として「Get some personal information about the user」が含まれています。エージェントはツールの説明文を読んで呼ぶかどうかを決めるため、この文言のままだと個人に関する情報の保存と参照を促す方向に働きます。

業務で使うなら、`TOOL_STORE_DESCRIPTION`と`TOOL_FIND_DESCRIPTION`を書き換えます。たとえば保存側を「プロジェクトの決定事項と手順だけを保存する。顧客の個人情報や認証情報は保存しない」とし、検索側を「作業を始める前に、このプロジェクトの決定事項を確認するときに使う」とします。説明文はエージェントへの指示にすぎず、保存を技術的に止めるものではありません。機微な情報を扱うリポジトリでは、次の読み取り専用の構成を選びます。

### QDRANT\_READ\_ONLYで検索専用にする構成とコレクションを分ける単位

`QDRANT_READ_ONLY=true`を指定すると、`qdrant-store`自体が登録されず、エージェントは検索しかできなくなります。前の節のPythonコードで管理者が内容を確認した知識だけを投入し、開発者のClaude Codeには読み取り専用で配る形にすると、誤った情報や秘密情報が記憶に入り込む経路を断てます。

ソースには、READMEの環境変数表に載っていない`QDRANT_ALLOW_ARBITRARY_FILTER`も定義されています。`true`にすると`qdrant-find`にQdrantのフィルタを渡す引数が現れ、エージェントが`metadata`で絞り込めるようになります。ただし、絞り込みはエージェント任せで権限の境界にはなりません。見せてよい範囲が違うなら、プロジェクトや部署ごとにコレクションとMCPの登録を分けます。

### 削除ツールが無いため古い記憶をREST APIで確認して消す手順

OSS版には削除と更新のツールがありません。方針が変わった後も古い記憶が検索に残り続けるため、定期的な棚卸しを運用に組み込みます。[Scroll points](https://api.qdrant.tech/api-reference/points/scroll-points)で中身を確かめ、[Delete points](https://api.qdrant.tech/api-reference/points/delete-points)にフィルタを渡して消します。

```
# 保存されている記憶を10件ずつ確認する
curl -X POST http://localhost:6333/collections/team-memory/points/scroll \
  -H "api-key: ${QDRANT_API_KEY}" -H "Content-Type: application/json" \
  -d '{"limit": 10, "with_payload": true, "with_vector": false}'

# metadata.project が "billing" の記憶だけを削除する
curl -X POST "http://localhost:6333/collections/team-memory/points/delete?wait=true" \
  -H "api-key: ${QDRANT_API_KEY}" -H "Content-Type: application/json" \
  -d '{"filter": {"must": [{"key": "metadata.project", "match": {"value": "billing"}}]}}'
```

MCP経由で保存された記憶は、エージェントが`metadata`を付けなかった場合に絞り込みの手がかりがありません。保存側の説明文で「必ずmetadataにprojectを入れる」と指示しておくと、後から消す範囲を特定しやすくなります。消す前には、[Qdrant Dockerの記事](https://www.issoh.co.jp/tech/details/19488/)で扱ったスナップショットを取っておきます。

### streamable-httpで共有サーバーにする場合に認証を前段で用意する理由

OSS版は`--transport`で`stdio`・`sse`・`streamable-http`を選べます。[MCP仕様（2026-07-28版）のTransports](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports)が標準として定めるのはstdioとStreamable HTTPの2つなので、新しく共有サーバーを立てるなら`streamable-http`を選びます。待ち受けは既定で`127.0.0.1`の8000番です。

公式のOSSページは、このサーバーには認証機能が無く、リモートで公開するなら認証付きのリバースプロキシやプライベートネットワークで守るよう求めています。Dockerで動かすときは`FASTMCP_SERVER_HOST=0.0.0.0`で全インターフェースに開くため、そのまま社内ネットワークに出すと、誰でも記憶の読み書きができる状態になります。複数のMCPサーバーをまとめて認証をかけたい場合は、[Docker MCP Gatewayの使い方](https://www.issoh.co.jp/tech/details/7981/)で解説しているゲートウェイ型の構成も候補です。

## Qdrant MCPを採用する条件と、Auto Memoryやmem0で足りる場面

エージェントに記憶を持たせる方法はQdrant MCPだけではありません。用途に対してどこまでの仕組みが要るかで、採用するかどうかを決めます。

### Qdrant MCPを入れる価値がある業務条件と見送るべき場面

Qdrant MCPを入れる価値があるのは、記憶をチームで共有したい場合と、量が増えて全文を毎回読ませるのが難しくなった場合です。複数の開発者が同じコレクションを参照し、設計判断や障害対応の記録を意味の近さで引ける点は、ファイルベースの記憶にはない利点です。Claude Code以外にCodexやCursorからも同じ記憶を使えます。

反対に、1人の開発者が1つのリポジトリで使うだけなら採用しません。Claude Codeには[Auto MemoryとMEMORY.md](https://www.issoh.co.jp/tech/details/10919/)があり、Qdrantのサーバー運用を増やさずに済みます。アプリのユーザーごとに会話の記憶を持たせたい場合も、記憶の抽出や更新まで面倒を見る[mem0のような記憶ライブラリ](https://www.issoh.co.jp/tech/details/17640/)のほうが向いています。OSS版は保存と検索しかできず、記憶の重複の整理や更新はすべて運用側の仕事になるためです。

### 社内文書の検索基盤へ広げる段階で外部に任せる作業と社内で持つ判断

Qdrant MCPを使い始めると、エージェントの記憶だけでなく、社内規程や設計書もまとめて検索させたいという要望が出てきます。その段階では、文書の分割、モデルの評価、権限ごとのコレクション設計、取り込みの自動化が必要になり、MCPサーバーの設定だけでは済みません。自前でMCPサーバーを作り込むなら[FastMCPでのサーバー実装](https://www.issoh.co.jp/tech/details/6507/)も選択肢に入ります。

社内に残すべきなのは、どの文書を誰に見せるかという権限の定義と、回答の正しさを判定する評価データです。基盤の構築や取り込みバッチ、検索精度の改善は外部に任せても判断を失いません。Qdrantを使った社内文書の検索基盤を検討している場合は、[RAG構築支援](https://www.issoh.co.jp/service/ai/rag/)で要件の整理から相談できます。全体の流れは[RAG構築の手順とは？データ整備から本番運用まで](https://www.issoh.co.jp/column/details/12920/)にまとめています。

## よくある質問

Qdrant MCPの導入と運用でつまずきやすい点に答えます。

### Qdrant MCPを使うのにOpenAIなど埋め込みAPIのキーは必要ですか？

公式のOSS版では不要です。埋め込みはサーバー内のFastEmbedが端末上で計算するため、`EMBEDDING_PROVIDER`も`fastembed`しか選べません。PyPIには`mcp-server-qdrant-openai`のように、OpenAIの埋め込みを使う第三者のサーバーもあります。こちらは公式版とは別物で、必要な環境変数も保存形式も異なります。同じコレクションを両方から使う構成は避けてください。

### Qdrantのサーバーを立てずにQdrant MCPを試せますか？

試せます。`QDRANT_URL`の代わりに`QDRANT_LOCAL_PATH`でディレクトリを指定すると、Qdrantのサーバーなしでローカルのファイルに保存する構成です。v0.8.1のsettings.pyは、`QDRANT_LOCAL_PATH`と`QDRANT_URL`または`QDRANT_API_KEY`を同時に指定すると起動時にエラーにします。1人で動作を確かめる用途に限り、チームで共有する段階でDockerかCloudのサーバーへ移します。

### Claude DesktopやCursorでも同じ設定で使えますか？

使えます。[GitHubのREADME](https://github.com/qdrant/mcp-server-qdrant)によると、Claude Desktopでは`claude_desktop_config.json`の`mcpServers`に、この記事の`.mcp.json`と同じ`command`・`args`・`env`を書く設定です。CursorやWindsurfの例では、サーバーを`--transport sse`で起動し、`http://localhost:8000/sse`を指定しています。公式のOSSページにはCodexとGitHub Copilot CLIの登録例も載っています。

### 埋め込みモデルを後から変えると保存済みの記憶はどうなりますか？

自動では作り直されません。v0.8.1のコードはモデル名からベクトル名を決めるため、モデルを変えたサーバーは既存のコレクションに合うベクトルを持たず、そのコレクションへの保存も検索も期待どおりに動きません。モデルを変えるときは新しいコレクション名を指定し、Scroll pointsで取り出した`document`を、前の節のPythonコードで新しいモデルの形式に入れ直します。

### MCPで保存した記憶の中身はどこで確認できますか？

手軽なのはQdrantのダッシュボードです。ローカルなら`http://localhost:6333/dashboard`を開くと、コレクションの各ポイントの`document`と`metadata`を画面で見られます。コマンドで確かめる場合に使うのはScroll pointsです。ツールの呼び出し自体を確かめたいときは、[MCP Inspector](https://github.com/modelcontextprotocol/inspector)でサーバーに直接つなぎ、`qdrant-find`の戻り値を確認できます。

## 関連記事

- [Qdrant Dockerの構築手順：docker run・Compose・永続化・APIキーとPythonで検索するまで【v1.20対応】](https://www.issoh.co.jp/tech/details/19488/)：Qdrant MCPの接続先をローカルに立てる手順
- [Qdrant Cloudの使い方：クラスタ作成・APIキー・Python接続とDockerからの移行【v1.20対応】](https://www.issoh.co.jp/tech/details/19490/)：チームで共有する記憶の置き場をマネージド版にする場合
- [MCP（Model Context Protocol）とは？仕組み・APIとの違い・MCPサーバーの作り方](https://www.issoh.co.jp/tech/details/5736/)：MCPサーバーとクライアントの関係の基礎
- [mem0とは？v3の破壊的変更・旧版のSQLインジェクションとAIエージェントに記憶を持たせる実装](https://www.issoh.co.jp/tech/details/17640/)：記憶の抽出と更新まで任せたい場合の選択肢
- [ベクトルDBとは？仕組み・インデックス構造・製品比較とpgvectorでの作り方【2026年版】](https://www.issoh.co.jp/tech/details/7691/)：Qdrantを含むベクトルDBの仕組みと製品の違い

---

出典: [Qdrant MCPの使い方：mcp-server-qdrantをClaude Codeにつなぐ設定と記憶ストア化【v0.8.1対応】](<https://www.issoh.co.jp/tech/details/19491/>)（株式会社一創）