データベース

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

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サーバーの作り方で解説しているので、ここではQdrant固有の部分に絞ります。

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

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

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

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

Qdrant Cloud MCPはhttps://api.cloud.qdrant.io/mcpで提供されるリモートサーバーで、OAuthでログインし、クラスタの作成・停止、バックアップ、請求の確認などを会話で行います。公式は、このサーバーはインフラ管理専用でコレクションやポイントは読み書きできないと明記しています。Qdrant Docs MCPは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の構築手順、マネージド版ならQdrant Cloudの使い方の手順で用意します。PyPIのmcp-server-qdrantはPython 3.10以上が必要です。

注意したいのは依存の固定です。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ドキュメントでは、--より前が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を生成する方法を参照してください。

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

OSS版が使える埋め込みはFastEmbedのモデルだけです。FastEmbedのSupported Modelsでは、既定の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にある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で中身を確かめ、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の記事で扱ったスナップショットを取っておきます。

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

OSS版は--transportでstdio・sse・streamable-httpを選べます。MCP仕様（2026-07-28版）の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の使い方で解説しているゲートウェイ型の構成も候補です。

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

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

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

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

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

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

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

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

よくある質問

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によると、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でサーバーに直接つなぎ、qdrant-findの戻り値を確認できます。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

この記事に関連するサービス

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.11.06　テックブログ ドコモ不正アクセス：最大29.5万件の流出項目と見舞金、My docomo停止の経過と偽連絡の見分け方
  2. 2026.11.03　テックブログ ネットマイル不正アクセスで最大549万人：対象確認と退会会員データを消す実装
  3. 2026.11.06　テックブログ あいおいニッセイ同和の不正アクセス：44.4万件の漏えい項目と窓口、止まった手続きの代わり
  4. 2026.11.06　テックブログ アイリスオーヤマ情報漏洩：アイリスプラザ770万人分の対象項目と本物の連絡の見分け方
  5. 2026.07.09　テックブログ Muse Imageとは？Metaの画像生成AIの使い方・API料金（1枚0.01ドル）と日本での提供状況【2026年10月】

RELATED POSTS 関連記事

一覧へ戻る

目次