Qdrant MCP

resmi

Qdrant 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-store kullanarak bir Qdrant koleksiyonuna kaydetmesini isteyin.
  • Anlamsal arama — qdrant-find ile doğal dildeki query üzerinden saklanan ilgili bilgileri bulun.
  • Koleksiyon seçme — Her çağrıda belirli bir collection_name hedefleyin veya COLLECTION_NAME aracı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_DESCRIPTION ve TOOL_FIND_DESCRIPTION değerlerini özelleştirin.
  • Salt okunur mod — Saklama işlemini devre dışı bırakıp yalnızca bilgi getirmeye izin vermek için QDRANT_READ_ONLY ayarını etkinleştirin.
  • Sonuçları ayarlama — Arama sonuçlarını QDRANT_SEARCH_LIMIT ile sınırlandırın ve EMBEDDING_MODEL aracılığıyla bir gömme modeli seçin.

Dokümantasyon

mcp-server-qdrant: Bir Qdrant MCP sunucusu

smithery badge

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

  1. qdrant-store
    • Qdrant veritabanında bazı bilgileri saklar
    • Girdi:
      • information (string): Saklanacak bilgi
      • metadata (JSON): Saklanacak isteğe bağlı meta veriler
      • collection_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ı
  2. qdrant-find
    • Qdrant veritabanından ilgili bilgileri alır
    • Girdi:
      • query (string): Arama için kullanılacak sorgu
      • collection_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_URL ve QDRANT_LOCAL_PATH değerlerini aynı anda sağlayamazsınız.

AdAçıklamaVarsayılan Değer
QDRANT_URLQdrant sunucusunun URL'siNone
QDRANT_API_KEYQdrant sunucusunun API anahtarıNone
COLLECTION_NAMEKullanılacak varsayılan koleksiyonun adıNone
QDRANT_LOCAL_PATHYerel Qdrant veritabanının yolu (QDRANT_URL yerine kullanılabilir)None
EMBEDDING_PROVIDERKullanılacak gömme sağlayıcısı (şu anda yalnızca "fastembed" desteklenir)fastembed
EMBEDDING_MODELKullanılacak gömme modelinin adısentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTIONStore aracı için özel açıklamaVarsayılan değer için bkz. settings.py
TOOL_FIND_DESCRIPTIONFind aracı için özel açıklamaVarsayılan değer için bkz. settings.py
QDRANT_SEARCH_LIMITAramadan döndürülecek en fazla sonuç sayısı10
QDRANT_READ_ONLYSalt 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şkeniAçıklamaVarsayılan Değer
FASTMCP_LOG_LEVELGünlük kaydı düzeyini ayarlar (DEBUG, INFO, WARNING, ERROR, CRITICAL)INFO
FASTMCP_DEBUGHata ayıklama modunu etkinleştirirfalse
FASTMCP_HOSTSunucunun bağlanacağı ana bilgisayar adresi (SSE ve HTTP taşıma protokolleri)127.0.0.1
FASTMCP_PORTSunucunun ç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ı gizlerfalse

[!NOTE] 0.9.0 sürümünden önce bu ayarlarda FASTMCP_SERVER_ öneki kullanılıyordu; örneğin FASTMCP_SERVER_HOST. Eski FASTMCP_SERVER_HOST, FASTMCP_SERVER_PORT ve FASTMCP_SERVER_DEBUG adları ç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ılabilir
  • sse: Server-Sent Events taşıması; uzak istemciler için idealdir
  • streamable-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:

  1. Kod parçacıklarını, belgeleri ve uygulama ayrıntılarını saklama
  2. Anlamsal aramaya dayalı olarak ilgili kod örneklerini alma
  3. 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

  1. 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
    
  2. 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:

  1. Açıklamalarıyla birlikte kod parçacıklarını saklamak için qdrant-store aracını kullanma.
  2. Doğal dil kullanarak ilgili kod parçacıklarını aramak için qdrant-find aracı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:

Install with UVX in VS Code Install with UVX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

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.

Gizlilik ve destek