Qdrant MCP
resmiQdrant vektör veritabanı kullanarak anlamsal arama.
Qdrant MCP ile neler yapabilirsiniz?
- Anıları saklama — Asistanınızdan, isteğe bağlı meta verilerle birlikte bilgileri
qdrant-storekullanarak bir Qdrant koleksiyonuna kaydetmesini isteyin. - Anlamsal arama —
qdrant-findile doğal dildekiqueryüzerinden saklanan ilgili bilgileri bulun. - Koleksiyon seçme — Her çağrıda belirli bir
collection_namehedefleyin veyaCOLLECTION_NAMEaracılığıyla varsayılan bir koleksiyon belirleyin. - Araç açıklamalarını özelleştirme — Sunucuyu kod parçacığı arama aracına dönüştürmek için
TOOL_STORE_DESCRIPTIONveTOOL_FIND_DESCRIPTIONdeğerlerini özelleştirin. - Salt okunur mod — Saklama işlemini devre dışı bırakıp yalnızca bilgi getirmeye izin vermek için
QDRANT_READ_ONLYayarını etkinleştirin. - Sonuçları ayarlama — Arama sonuçlarını
QDRANT_SEARCH_LIMITile sınırlandırın veEMBEDDING_MODELaracılığıyla bir gömme modeli seçin.
Dokümantasyon
mcp-server-qdrant: Bir Qdrant MCP sunucusu
Model Context Protocol (MCP), LLM uygulamaları ile harici veri kaynakları ve araçlar arasında sorunsuz entegrasyon sağlayan açık bir protokoldür. İster yapay zekâ destekli bir IDE geliştiriyor, ister bir sohbet arayüzünü iyileştiriyor, ister özel yapay zekâ iş akışları oluşturuyor olun, MCP, LLM'leri ihtiyaç duydukları bağlama bağlamak için standartlaştırılmış bir yol sunar.
Bu depo, bir vektör arama motoru olan Qdrant için MCP sunucusu oluşturma örneğidir.
Genel Bakış
Qdrant vektör arama motorunda anıları saklamak ve almak için resmi bir Model Context Protocol sunucusu. Qdrant veritabanının üzerinde anlamsal bir bellek katmanı görevi görür.
Bileşenler
Araçlar
qdrant-store- Qdrant veritabanında bazı bilgileri saklar
- Girdi:
information(string): Saklanacak bilgimetadata(JSON): Saklanacak isteğe bağlı meta verilercollection_name(string): Bilginin saklanacağı koleksiyonun adı. Varsayılan koleksiyon adı yoksa bu alan zorunludur. Varsayılan koleksiyon adı varsa bu alan etkin değildir.
- Döndürür: Onay mesajı
qdrant-find- Qdrant veritabanından ilgili bilgileri alır
- Girdi:
query(string): Arama için kullanılacak sorgucollection_name(string): Bilginin saklanacağı koleksiyonun adı. Varsayılan koleksiyon adı yoksa bu alan zorunludur. Varsayılan koleksiyon adı varsa bu alan etkin değildir.
- Döndürür: Qdrant veritabanında saklanan bilgileri ayrı mesajlar olarak
Ortam Değişkenleri
Yapılandırma ortam değişkenleri aracılığıyla yapılır. Tek komut satırı bağımsız değişkeni, taşıma protokolünü seçmek için kullanılan --transport değeridir.
[!NOTE]
QDRANT_URLveQDRANT_LOCAL_PATHdeğerlerini aynı anda sağlayamazsınız.
| Ad | Açıklama | Varsayılan Değer |
|---|---|---|
QDRANT_URL | Qdrant sunucusunun URL'si | None |
QDRANT_API_KEY | Qdrant sunucusunun API anahtarı | None |
COLLECTION_NAME | Kullanılacak varsayılan koleksiyonun adı | None |
QDRANT_LOCAL_PATH | Yerel Qdrant veritabanının yolu (QDRANT_URL yerine kullanılabilir) | None |
EMBEDDING_PROVIDER | Kullanılacak gömme sağlayıcısı (şu anda yalnızca "fastembed" desteklenir) | fastembed |
EMBEDDING_MODEL | Kullanılacak gömme modelinin adı | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | Store aracı için özel açıklama | Varsayılan değer için bkz. settings.py |
TOOL_FIND_DESCRIPTION | Find aracı için özel açıklama | Varsayılan değer için bkz. settings.py |
QDRANT_SEARCH_LIMIT | Aramadan döndürülecek en fazla sonuç sayısı | 10 |
QDRANT_READ_ONLY | Salt okunur modu etkinleştirir (qdrant-store aracını devre dışı bırakır) | false |
FastMCP Ortam Değişkenleri
mcp-server-qdrant, FastMCP tabanlı olduğundan tüm FastMCP ortam değişkenlerini de destekler. En
önemlileri aşağıda listelenmiştir:
| Ortam Değişkeni | Açıklama | Varsayılan Değer |
|---|---|---|
FASTMCP_LOG_LEVEL | Günlük kaydı düzeyini ayarlar (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
FASTMCP_DEBUG | Hata ayıklama modunu etkinleştirir | false |
FASTMCP_HOST | Sunucunun bağlanacağı ana bilgisayar adresi (SSE ve HTTP taşıma protokolleri) | 127.0.0.1 |
FASTMCP_PORT | Sunucunun çalışacağı bağlantı noktası (SSE ve HTTP taşıma protokolleri) | 8000 |
FASTMCP_MASK_ERROR_DETAILS | İstemcilere gönderilen araç hata mesajlarında istisna ayrıntılarını gizler | false |
[!NOTE] 0.9.0 sürümünden önce bu ayarlarda
FASTMCP_SERVER_öneki kullanılıyordu; örneğinFASTMCP_SERVER_HOST. EskiFASTMCP_SERVER_HOST,FASTMCP_SERVER_PORTveFASTMCP_SERVER_DEBUGadları çalışmaya devam eder ancak kullanımdan kaldırılmıştır ve gelecekteki bir sürümde kaldırılacaktır. Her iki ad da ayarlanırsa yeni olan önceliklidir.
Kurulum
uvx kullanımı
uvx kullanırken mcp-server-qdrant'ı doğrudan çalıştırmak için özel bir kurulum gerekmez.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant
Taşıma Protokolleri
Sunucu, --transport bayrağı kullanılarak belirtilebilen farklı taşıma protokollerini destekler:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse
Desteklenen taşıma protokolleri:
stdio(varsayılan): Standart girdi/çıktı taşıması; yalnızca yerel MCP istemcileri tarafından kullanılabilirsse: Server-Sent Events taşıması; uzak istemciler için idealdirstreamable-http: Streamable HTTP taşıması; uzak istemciler için idealdir ve SSE'den daha yenidir
Belirtilmezse varsayılan taşıma protokolü stdio olur.
SSE taşıması kullanıldığında sunucu, belirtilen bağlantı noktasında dinler ve gelen bağlantıları bekler. Varsayılan
bağlantı noktası 8000'dir; ancak FASTMCP_PORT ortam değişkeni kullanılarak değiştirilebilir.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_PORT=1234 \
uvx mcp-server-qdrant --transport sse
Docker kullanımı
MCP sunucusunu derlemek ve çalıştırmak için bir Dockerfile mevcuttur:
# 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] Sunucunun tüm ağ arayüzlerinde dinlemesi için
FASTMCP_HOST="0.0.0.0"değerini ayarladığımızı unutmayın. Bu, sunucuyu bir Docker kapsayıcısında çalıştırırken gereklidir.
Smithery ile kurulum
Qdrant MCP Server'ı Smithery aracılığıyla Claude Desktop için otomatik olarak kurmak üzere:
npx @smithery/cli install mcp-server-qdrant --client claude
Claude Desktop'ı elle yapılandırma
Bu sunucuyu Claude Desktop uygulamasıyla kullanmak için aşağıdaki yapılandırmayı
claude_desktop_config.json dosyanızın "mcpServers" bölümüne ekleyin:
{
"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"
}
}
}
Yerel Qdrant modu için:
{
"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"
}
}
}
Bu MCP sunucusu, belirtilen ada sahip bir koleksiyon yoksa onu otomatik olarak oluşturur.
Varsayılan olarak sunucu, anıları kodlamak için sentence-transformers/all-MiniLM-L6-v2 gömme modelini kullanır.
Şimdilik yalnızca FastEmbed modelleri desteklenmektedir.
Diğer araçları destekleme
Bu MCP sunucusu, MCP ile uyumlu tüm istemcilerle kullanılabilir. Örneğin, Model Context Protocol için yerleşik destek sunan Cursor ve VS Code ile kullanabilirsiniz.
Cursor/Windsurf ile kullanım
Araç açıklamalarını özelleştirerek bu MCP sunucusunu Cursor veya Windsurf için kod arama aracı olarak yapılandırabilirsiniz:
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
Ardından Cursor/Windsurf ayarlarında, SSE taşıma protokolünü kullanarak çalışan bu sunucuya işaret edip MCP sunucusunu yapılandırabilirsiniz. Cursor'a MCP sunucusu ekleme açıklamasını Cursor belgelerinde bulabilirsiniz. Cursor/Windsurf'ü yerel olarak çalıştırıyorsanız aşağıdaki URL'yi kullanabilirsiniz:
http://localhost:8000/sse
[!TIP] Cursor/Windsurf'ü MCP sunucusuna bağlamak için tercih edilen yöntem olarak SSE taşımasını öneriyoruz; çünkü uzak bağlantıları destekleyebilir. Bu sayede sunucuyu ekibinizle paylaşmak veya bulut ortamında kullanmak kolaylaşır.
Bu yapılandırma, Qdrant MCP sunucusunu aşağıdakileri yapabilen özel bir kod arama aracına dönüştürür:
- Kod parçacıklarını, belgeleri ve uygulama ayrıntılarını saklama
- Anlamsal aramaya dayalı olarak ilgili kod örneklerini alma
- Geliştiricilerin belirli uygulamaları veya kullanım kalıplarını bulmasına yardımcı olma
Veritabanını, kod parçacıklarının doğal dildeki açıklamalarını (information parametresinde)
gerçek kodla (metadata.code özelliğinde) birlikte saklayarak doldurabilir, ardından aradığınız şeyi açıklayan
doğal dil sorgularıyla bunları arayabilirsiniz.
[!NOTE] Yukarıda verilen araç açıklamaları örnektir ve kullanım durumunuza göre özelleştirilmeleri gerekebilir. Ekibinizin iş akışına ve saklayıp almak istediğiniz kod parçacıklarının türlerine daha iyi uyacak şekilde açıklamaları düzenlemeyi düşünebilirsiniz.
mcp-server-qdrant'ı başarıyla kurduysanız ancak Cursor ile hâlâ çalıştıramıyorsanız, MCP araçlarının aracı yeni bir kod
parçacığı oluşturduğunda her zaman kullanılmasını sağlamak için lütfen Cursor kuralları oluşturmayı
düşünün. MCP sunucusunun belgeler veya diğer içerik türleri için kullanılmasını önlemek amacıyla kuralları yalnızca
belirli dosya türlerinde çalışacak şekilde kısıtlayabilirsiniz.
Claude Code ile kullanım
Claude Code'u bu MCP sunucusuna bağlayarak mevcut kod tabanınızda anlamsal arama yapmasını sağlayabilir ve yeteneklerini geliştirebilirsiniz.
mcp-server-qdrant'ı ayarlama
-
MCP sunucusunu Claude Code'a ekleyin:
# 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 -
Sunucunun eklendiğini doğrulayın:
claude mcp list
Claude Code'da anlamsal kod aramasını kullanma
TOOL_STORE_DESCRIPTION ve TOOL_FIND_DESCRIPTION içinde belirtilen araç açıklamaları, Claude Code'a MCP sunucusunu nasıl
kullanacağını gösterir. Yukarıda verilen açıklamalar örnektir ve kullanım durumunuza göre özelleştirilmeleri gerekebilir. Ancak
Claude Code şimdiden şunları yapabiliyor olmalıdır:
- Açıklamalarıyla birlikte kod parçacıklarını saklamak için
qdrant-storearacını kullanma. - Doğal dil kullanarak ilgili kod parçacıklarını aramak için
qdrant-findaracını kullanma.
MCP sunucusunu geliştirme modunda çalıştırma
MCP sunucusu, mcp dev komutu kullanılarak geliştirme modunda çalıştırılabilir. Bu komut sunucuyu başlatır ve MCP
denetleyicisini tarayıcınızda açar.
COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py
VS Code ile kullanım
Tek tıklamayla kurulum için aşağıdaki yükleme düğmelerinden birine tıklayın:
Elle kurulum
Aşağıdaki JSON bloğunu VS Code'daki Kullanıcı Ayarları (JSON) dosyanıza ekleyin. Bunu yapmak için Ctrl + Shift + P tuşlarına basıp Preferences: Open User Settings (JSON) yazabilirsiniz.
{
"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 kullanmayı tercih ediyorsanız bunun yerine şu yapılandırmayı ekleyin:
{
"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}"
}
}
}
}
}
Alternatif olarak, çalışma alanınızda aşağıdaki içeriğe sahip bir .vscode/mcp.json dosyası oluşturabilirsiniz:
{
"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 ile çalışma alanı yapılandırması için .vscode/mcp.json dosyasında şunu kullanın:
{
"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}"
}
}
}
}
Katkıda Bulunma
mcp-server-qdrant'ın nasıl geliştirilebileceğine dair önerileriniz varsa veya bir hata bildirmek istiyorsanız bir sorun açın! Her türlü katkınızı memnuniyetle karşılarız.
mcp-server-qdrant'ı yerel olarak test etme
MCP denetleyicisi, MCP sunucularını test etmek ve hata ayıklamak için kullanılan bir geliştirici aracıdır. Hem bir istemci arayüzü (varsayılan bağlantı noktası 5173) hem de bir MCP proxy sunucusu (varsayılan bağlantı noktası 3000) çalıştırır. Denetleyiciyi kullanmak için istemci arayüzünü tarayıcınızda açın.
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py
Başlatıldıktan sonra denetleyici arayüzüne erişmek için tarayıcınızda http://localhost:5173 adresini açın.
Lisans
Bu MCP sunucusu Apache License 2.0 kapsamında lisanslanmıştır. Bu, Apache License 2.0'ın hüküm ve koşullarına tabi olarak yazılımı kullanabileceğiniz, değiştirebileceğiniz ve dağıtabileceğiniz anlamına gelir. Daha fazla bilgi için lütfen proje deposundaki LICENSE dosyasına bakın.