Qdrant MCP
resmiPencarian semantik menggunakan basis data vektor Qdrant.
Apa yang bisa Anda lakukan dengan Qdrant MCP?
- Simpan memori — Minta asisten Anda menyimpan informasi, dengan metadata opsional, ke dalam koleksi Qdrant menggunakan
qdrant-store. - Pencarian semantik — Ambil informasi tersimpan yang relevan melalui
querydalam bahasa alami denganqdrant-find. - Pilih koleksi — Tentukan
collection_nametertentu untuk setiap pemanggilan, atau tetapkan nilai default melaluiCOLLECTION_NAME. - Sesuaikan deskripsi alat — Sesuaikan
TOOL_STORE_DESCRIPTIONdanTOOL_FIND_DESCRIPTIONuntuk mengubah server menjadi alat pencarian cuplikan kode. - Mode hanya-baca — Aktifkan
QDRANT_READ_ONLYuntuk menonaktifkan penyimpanan dan hanya mengizinkan pengambilan. - Atur hasil — Batasi hasil pencarian dengan
QDRANT_SEARCH_LIMITdan pilih model embedding melaluiEMBEDDING_MODEL.
Dokumentasi
mcp-server-qdrant: Server MCP Qdrant
Model Context Protocol (MCP) adalah protokol terbuka yang memungkinkan integrasi lancar antara aplikasi LLM dan sumber data serta alat eksternal. Baik Anda sedang membangun IDE bertenaga AI, menyempurnakan antarmuka obrolan, atau membuat alur kerja AI khusus, MCP menyediakan cara standar untuk menghubungkan LLM dengan konteks yang mereka butuhkan.
Repositori ini adalah contoh cara membuat server MCP untuk Qdrant, mesin pencarian vektor.
Ringkasan
Server Model Context Protocol resmi untuk menyimpan dan mengambil memori di mesin pencarian vektor Qdrant. Server ini berfungsi sebagai lapisan memori semantik di atas basis data Qdrant.
Komponen
Alat
qdrant-store- Menyimpan informasi di basis data Qdrant
- Input:
information(string): Informasi yang akan disimpanmetadata(JSON): Metadata opsional yang akan disimpancollection_name(string): Nama koleksi tempat informasi akan disimpan. Kolom ini wajib diisi jika tidak ada nama koleksi default. Jika ada nama koleksi default, kolom ini tidak diaktifkan.
- Mengembalikan: Pesan konfirmasi
qdrant-find- Mengambil informasi yang relevan dari basis data Qdrant
- Input:
query(string): Kueri yang digunakan untuk pencariancollection_name(string): Nama koleksi tempat informasi akan disimpan. Kolom ini wajib diisi jika tidak ada nama koleksi default. Jika ada nama koleksi default, kolom ini tidak diaktifkan.
- Mengembalikan: Informasi yang disimpan di basis data Qdrant sebagai pesan terpisah
Variabel Lingkungan
Konfigurasi dilakukan melalui variabel lingkungan. Satu-satunya argumen baris perintah adalah --transport, yang digunakan untuk memilih protokol transportasi.
[!NOTE] Anda tidak dapat memberikan
QDRANT_URLdanQDRANT_LOCAL_PATHsecara bersamaan.
| Nama | Deskripsi | Nilai Default |
|---|---|---|
QDRANT_URL | URL server Qdrant | None |
QDRANT_API_KEY | Kunci API untuk server Qdrant | None |
COLLECTION_NAME | Nama koleksi default yang akan digunakan. | None |
QDRANT_LOCAL_PATH | Jalur ke basis data Qdrant lokal (alternatif untuk QDRANT_URL) | None |
EMBEDDING_PROVIDER | Penyedia embedding yang akan digunakan (saat ini hanya "fastembed" yang didukung) | fastembed |
EMBEDDING_MODEL | Nama model embedding yang akan digunakan | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | Deskripsi khusus untuk alat store | Lihat default di settings.py |
TOOL_FIND_DESCRIPTION | Deskripsi khusus untuk alat find | Lihat default di settings.py |
QDRANT_SEARCH_LIMIT | Jumlah maksimum hasil yang dikembalikan dari pencarian | 10 |
QDRANT_READ_ONLY | Aktifkan mode hanya-baca (menonaktifkan alat qdrant-store) | false |
Variabel Lingkungan FastMCP
Karena mcp-server-qdrant berbasis FastMCP, server ini juga mendukung semua variabel lingkungan FastMCP. Variabel yang paling
penting tercantum di bawah ini:
| Variabel Lingkungan | Deskripsi | Nilai Default |
|---|---|---|
FASTMCP_LOG_LEVEL | Mengatur tingkat pencatatan log (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
FASTMCP_DEBUG | Mengaktifkan mode debug | false |
FASTMCP_HOST | Alamat host untuk mengikat server (transportasi SSE dan HTTP) | 127.0.0.1 |
FASTMCP_PORT | Port untuk menjalankan server (transportasi SSE dan HTTP) | 8000 |
FASTMCP_MASK_ERROR_DETAILS | Menyembunyikan detail pengecualian dari pesan kesalahan alat yang dikirim ke klien | false |
[!NOTE] Sebelum versi 0.9.0, pengaturan ini menggunakan awalan
FASTMCP_SERVER_, misalnyaFASTMCP_SERVER_HOST. Nama lamaFASTMCP_SERVER_HOST,FASTMCP_SERVER_PORT, danFASTMCP_SERVER_DEBUGmasih berfungsi, tetapi sudah usang dan akan dihapus pada rilis mendatang. Jika kedua nama diatur, nama baru yang akan digunakan.
Instalasi
Menggunakan uvx
Saat menggunakan uvx, tidak diperlukan instalasi khusus untuk langsung menjalankan mcp-server-qdrant.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant
Protokol Transportasi
Server mendukung berbagai protokol transportasi yang dapat ditentukan menggunakan flag --transport:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse
Protokol transportasi yang didukung:
stdio(default): Transportasi input/output standar, mungkin hanya dapat digunakan oleh klien MCP lokalsse: Transportasi Server-Sent Events, cocok untuk klien jarak jauhstreamable-http: Transportasi Streamable HTTP, cocok untuk klien jarak jauh dan lebih baru daripada SSE
Transportasi default adalah stdio jika tidak ditentukan.
Saat transportasi SSE digunakan, server akan mendengarkan pada port yang ditentukan dan menunggu koneksi masuk. Port default
adalah 8000, tetapi dapat diubah menggunakan variabel lingkungan FASTMCP_PORT.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_PORT=1234 \
uvx mcp-server-qdrant --transport sse
Menggunakan Docker
Dockerfile tersedia untuk membangun dan menjalankan server MCP:
# Build the container
docker build -t mcp-server-qdrant .
# Run the container
docker run -p 8000:8000 \
-e FASTMCP_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] Perhatikan bahwa kami mengatur
FASTMCP_HOST="0.0.0.0"agar server mendengarkan di semua antarmuka jaringan. Hal ini diperlukan saat menjalankan server di dalam kontainer Docker.
Menginstal melalui Smithery
Untuk menginstal Qdrant MCP Server secara otomatis untuk Claude Desktop melalui Smithery:
npx @smithery/cli install mcp-server-qdrant --client claude
Konfigurasi manual Claude Desktop
Untuk menggunakan server ini dengan aplikasi Claude Desktop, tambahkan konfigurasi berikut ke bagian "mcpServers" di
claude_desktop_config.json Anda:
{
"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"
}
}
}
Untuk mode Qdrant lokal:
{
"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"
}
}
}
Server MCP ini akan otomatis membuat koleksi dengan nama yang ditentukan jika koleksi tersebut belum ada.
Secara default, server akan menggunakan model embedding sentence-transformers/all-MiniLM-L6-v2 untuk mengodekan memori.
Untuk saat ini, hanya model FastEmbed yang didukung.
Dukungan untuk alat lain
Server MCP ini dapat digunakan dengan klien apa pun yang kompatibel dengan MCP. Misalnya, Anda dapat menggunakannya dengan Cursor dan VS Code, yang menyediakan dukungan bawaan untuk Model Context Protocol.
Menggunakan dengan Cursor/Windsurf
Anda dapat mengonfigurasi server MCP ini agar berfungsi sebagai alat pencarian kode untuk Cursor atau Windsurf dengan menyesuaikan deskripsi alat:
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
Di Cursor/Windsurf, Anda kemudian dapat mengonfigurasi server MCP di pengaturan dengan mengarahkannya ke server yang sedang berjalan ini menggunakan protokol transportasi SSE. Petunjuk untuk menambahkan server MCP ke Cursor dapat ditemukan di dokumentasi Cursor. Jika Anda menjalankan Cursor/Windsurf secara lokal, Anda dapat menggunakan URL berikut:
http://localhost:8000/sse
[!TIP] Kami menyarankan transportasi SSE sebagai cara yang diutamakan untuk menghubungkan Cursor/Windsurf ke server MCP, karena mendukung koneksi jarak jauh. Dengan begitu, server dapat dengan mudah dibagikan kepada tim atau digunakan di lingkungan cloud.
Konfigurasi ini mengubah server MCP Qdrant menjadi alat pencarian kode khusus yang dapat:
- Menyimpan cuplikan kode, dokumentasi, dan detail implementasi
- Mengambil contoh kode yang relevan berdasarkan pencarian semantik
- Membantu pengembang menemukan implementasi atau pola penggunaan tertentu
Anda dapat mengisi basis data dengan menyimpan deskripsi cuplikan kode dalam bahasa alami (di parameter information)
beserta kode sebenarnya (di properti metadata.code), lalu mencarinya menggunakan kueri bahasa alami
yang menjelaskan hal yang Anda cari.
[!NOTE] Deskripsi alat yang diberikan di atas hanyalah contoh dan mungkin perlu disesuaikan dengan kasus penggunaan Anda. Pertimbangkan untuk menyesuaikan deskripsi agar lebih sesuai dengan alur kerja tim dan jenis cuplikan kode tertentu yang ingin Anda simpan dan ambil.
Jika Anda berhasil menginstal mcp-server-qdrant, tetapi masih tidak dapat menggunakannya dengan Cursor, pertimbangkan
untuk membuat aturan Cursor agar alat MCP selalu digunakan saat
agen menghasilkan cuplikan kode baru. Anda dapat membatasi aturan agar hanya berlaku untuk jenis file tertentu, sehingga server MCP tidak digunakan untuk dokumentasi atau jenis konten lainnya.
Menggunakan dengan Claude Code
Anda dapat meningkatkan kemampuan Claude Code dengan menghubungkannya ke server MCP ini, sehingga memungkinkan pencarian semantik pada basis kode yang sudah ada.
Menyiapkan mcp-server-qdrant
-
Tambahkan server MCP ke 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 -
Verifikasi bahwa server telah ditambahkan:
claude mcp list
Menggunakan Pencarian Kode Semantik di Claude Code
Deskripsi alat yang ditentukan di TOOL_STORE_DESCRIPTION dan TOOL_FIND_DESCRIPTION memandu Claude Code tentang cara menggunakan
server MCP. Deskripsi yang diberikan di atas hanyalah contoh dan mungkin perlu disesuaikan dengan kasus penggunaan Anda. Namun,
Claude Code seharusnya sudah dapat:
- Menggunakan alat
qdrant-storeuntuk menyimpan cuplikan kode beserta deskripsinya. - Menggunakan alat
qdrant-finduntuk mencari cuplikan kode yang relevan menggunakan bahasa alami.
Menjalankan Server MCP dalam Mode Pengembangan
Server MCP dapat dijalankan dalam mode pengembangan menggunakan perintah mcp dev. Perintah ini akan memulai server dan membuka MCP
inspector di browser Anda.
COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py
Menggunakan dengan VS Code
Untuk instalasi sekali klik, klik salah satu tombol instalasi di bawah ini:
Instalasi Manual
Tambahkan blok JSON berikut ke file User Settings (JSON) di VS Code. Anda dapat melakukannya dengan menekan Ctrl + Shift + P lalu mengetik 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}"
}
}
}
}
}
Atau, jika Anda lebih suka menggunakan Docker, tambahkan konfigurasi ini:
{
"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}"
}
}
}
}
}
Sebagai alternatif, Anda dapat membuat file .vscode/mcp.json di ruang kerja dengan konten berikut:
{
"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}"
}
}
}
}
Untuk konfigurasi ruang kerja dengan Docker, gunakan ini di .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}"
}
}
}
}
Kontribusi
Jika Anda memiliki saran untuk meningkatkan mcp-server-qdrant atau ingin melaporkan bug, buat issue! Kami menyambut semua kontribusi.
Menguji mcp-server-qdrant secara lokal
MCP inspector adalah alat pengembang untuk menguji dan men-debug server MCP. Alat ini menjalankan UI klien (port default 5173) dan server proksi MCP (port default 3000). Buka UI klien di browser Anda untuk menggunakan inspector.
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py
Setelah dimulai, buka http://localhost:5173 di browser untuk mengakses antarmuka inspector.
Lisensi
Server MCP ini dilisensikan di bawah Apache License 2.0. Artinya, Anda bebas menggunakan, mengubah, dan mendistribusikan perangkat lunak ini, dengan tunduk pada syarat dan ketentuan Apache License 2.0. Untuk detail selengkapnya, lihat file LICENSE di repositori proyek.