Qdrant MCP

resmi

Qdrant vektör veritabanı kullanarak anlamsal arama.

Qdrant MCP ile neler yapabilirsiniz?

Qdrant'ı AI asistanınız için anlamsal bellek katmanı olarak kullanın; bilgileri tam anahtar kelimeler yerine anlamlarına göre saklayıp geri çağırmasını sağlayın.

Anlamsal bellekleri saklayın — Asistanınızdan, daha sonra geri çağırmak üzere bilgileri isteğe bağlı meta verilerle birlikte qdrant-store aracılığıyla Qdrant'a kaydetmesini isteyin.
İlgili bellekleri geri çağırın — Saklanan bilgileri doğal dil sorgusuyla aramak ve eşleşen sonuçları almak için qdrant-find kullanın.
Bir kod parçacığı kitaplığı oluşturun — Kod parçacıklarını açıklamalarıyla saklayın ve Cursor ile Claude Code kurulumlarında gösterildiği gibi anlamsal olarak geri çağırın.
Belirli koleksiyonları hedefleyin — collection_name ile adlandırılmış bir koleksiyonda saklayın veya arayın ya da COLLECTION_NAME tarafından ayarlanan varsayılanı kullanın.

Dokümantasyon

mcp-server-qdrant: Bir Qdrant MCP sunucusu

Model Context Protocol (MCP), LLM uygulamaları ile harici veri kaynakları ve araçlar arasında kesintisiz entegrasyon sağlayan açık bir protokoldür. İster yapay zeka destekli bir IDE geliştiriyor, ister bir sohbet arayüzünü geliştiriyor, isterse özel yapay zeka iş akışları oluşturuyor olun, MCP, LLM'leri ihtiyaç duydukları bağlama bağlamak için standart bir yol sağlar.

Bu depo, bir vektör arama motoru olan Qdrant için bir MCP sunucusunun nasıl oluşturulacağına dair bir örnektir.

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 saklayın
- Girdi:
  - information (dize): Saklanacak bilgi
  - metadata (JSON): Saklanacak isteğe bağlı meta veriler
  - collection_name (dize): Bilgilerin saklanacağı koleksiyonun adı. Varsayılan koleksiyon adı yoksa bu alan gereklidir. Varsayılan bir koleksiyon adı varsa, bu alan etkin değildir.
- Döndürür: Onay mesajı
qdrant-find
- Qdrant veritabanından ilgili bilgileri alın
- Girdi:
  - query (dize): Arama için kullanılacak sorgu
  - collection_name (dize): Bilgilerin saklanacağı koleksiyonun adı. Varsayılan koleksiyon adı yoksa bu alan gereklidir. Varsayılan bir koleksiyon adı varsa, bu alan etkin değildir.
- Döndürür: Qdrant veritabanında ayrı mesajlar olarak saklanan bilgiler

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'dir.

[!NOT] Aynı anda hem QDRANT_URL hem de QDRANT_LOCAL_PATH sağlayamazsınız.

Ad	Açıklama	Varsayılan Değer
`QDRANT_URL`	Qdrant sunucusunun URL'si	Yok
`QDRANT_API_KEY`	Qdrant sunucusu için API anahtarı	Yok
`COLLECTION_NAME`	Kullanılacak varsayılan koleksiyonun adı.	Yok
`QDRANT_LOCAL_PATH`	Yerel Qdrant veritabanının yolu (`QDRANT_URL` alternatifi)	Yok
`EMBEDDING_PROVIDER`	Kullanılacak yerleştirme sağlayıcısı (şu anda yalnızca "fastembed" desteklenmektedir)	`fastembed`
`EMBEDDING_MODEL`	Kullanılacak yerleştirme modelinin adı	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	Mağaza aracı için özel açıklama	`settings.py` içindeki varsayılana bakın
`TOOL_FIND_DESCRIPTION`	Bulma aracı için özel açıklama	`settings.py` içindeki varsayılana bakın
`QDRANT_SEARCH_LIMIT`	Aramadan döndürülecek maksimum sonuç sayısı	`10`
`QDRANT_READ_ONLY`	Salt okunur modu etkinleştir (`qdrant-store` aracını devre dışı bırakır)	`false`

FastMCP Ortam Değişkenleri

mcp-server-qdrant FastMCP'ye dayandığından, 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 ayarlayın (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Hata ayıklama modunu etkinleştir	`false`
`FASTMCP_SERVER_HOST`	Sunucunun bağlanacağı ana bilgisayar adresi	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Sunucunun çalışacağı bağlantı noktası	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Yinelenen kaynaklar için davranış (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Yinelenen araçlar için davranış (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Yinelenen istemler için davranış (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	Sunucu ortamına yüklenecek bağımlılıkların listesi	`[]`

[!NOT] Sunucuya özel ayarlar FASTMCP_SERVER_ önekini kullanır. Bu, gelecek sürümlerde değişebilir.

Kurulum

uvx kullanarak

uvx kullanırken mcp-server-qdrant'ı doğrudan çalıştırmak için belirli 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: Uzak istemciler için mükemmel olan Server-Sent Events taşıması
streamable-http: Uzak istemciler için mükemmel olan, SSE'den daha yeni olan Akışkan HTTP taşıması

Belirtilmezse varsayılan taşıma stdio'dir.

SSE taşıması kullanıldığında, sunucu belirtilen bağlantı noktasını dinler ve gelen bağlantıları bekler. Varsayılan bağlantı noktası 8000'dir, ancak FASTMCP_SERVER_PORT ortam değişkeni kullanılarak değiştirilebilir.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_PORT=1234 \
uvx mcp-server-qdrant --transport sse

Docker kullanarak

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_SERVER_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

[!İPUCU] Sunucunun tüm ağ arayüzlerini dinlemesi için FASTMCP_SERVER_HOST="0.0.0.0" değerini ayarladığımızı lütfen unutmayın. Bu, sunucuyu bir Docker kapsayıcısında çalıştırırken gereklidir.

Smithery aracılığıyla kurulum

Qdrant MCP Sunucusunu Smithery aracılığıyla Claude Desktop için otomatik olarak kurmak için:

npx @smithery/cli install mcp-server-qdrant --client claude

Claude Desktop'un manuel yapılandırması

Bu sunucuyu Claude Desktop uygulamasıyla kullanmak için, claude_desktop_config.json dosyanızın "mcpServers" bölümüne aşağıdaki yapılandırmayı 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 otomatik olarak oluşturur.

Varsayılan olarak, sunucu anıları kodlamak için sentence-transformers/all-MiniLM-L6-v2 yerleştirme modelini kullanır. Şimdilik yalnızca FastEmbed modelleri desteklenmektedir.

Diğer araçlar için destek

Bu MCP sunucusu, MCP uyumlu herhangi bir istemciyle kullanılabilir. Örneğin, Model Context için yerleşik destek sağlayan Cursor ve VS Code ile kullanabilirsiniz. Protokol.

Cursor/Windsurf ile kullanma

Bu MCP sunucusunu, araç açıklamalarını özelleştirerek Cursor veya Windsurf için bir kod arama aracı olarak çalışacak şekilde 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

Cursor/Windsurf'te, SSE taşıma protokolünü kullanarak bu çalışan sunucuyu işaret ederek MCP sunucusunu ayarlarınızda yapılandırabilirsiniz. Cursor'a MCP sunucusu ekleme açıklaması Cursor belgelerinde bulunabilir. Eğer Cursor/Windsurf'ü yerel olarak çalıştırıyorsanız, aşağıdaki URL'yi kullanabilirsiniz:

http://localhost:8000/sse

[!İPUCU] Uzak bağlantıları destekleyebildiği için Cursor/Windsurf'ü MCP sunucusuna bağlamanın tercih edilen yolu olarak SSE taşımasını öneriyoruz. Bu, sunucuyu ekibinizle paylaşmayı veya bir bulut ortamında kullanmayı kolaylaştırı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ı saklayın
Anlamsal aramaya dayalı olarak ilgili kod örneklerini alın
Geliştiricilerin belirli uygulamaları veya kullanım kalıplarını bulmasına yardımcı olun

Veritabanını, kod parçacıklarının doğal dil açıklamalarını (information parametresinde) gerçek kodla birlikte (metadata.code özelliğinde) saklayarak doldurabilir ve ardından ne aradığınızı açıklayan doğal dil sorgularını kullanarak bunları arayabilirsiniz.

[!NOT] Yukarıda sağlanan araç açıklamaları örnektir ve belirli kullanım durumunuz için özelleştirilmesi gerekebilir. Açıklamaları, ekibinizin iş akışına ve saklamak ve almak istediğiniz belirli kod parçacığı türlerine daha iyi uyacak şekilde ayarlamayı düşünün.

mcp-server-qdrant başarıyla kurduysanız ancak yine de Cursor ile çalıştıramıyorsanız, lütfen Cursor kurallarını oluşturmayı düşünün, böylece MCP araçları aracı yeni bir kod parçacığı ürettiğinde her zaman kullanılır. MCP sunucusunu belgeler veya diğer içerik türleri için kullanmaktan kaçınmak için kuralları yalnızca belirli dosya türleri için çalışacak şekilde sınırlayabilirsiniz.

Claude Code ile kullanma

Bu MCP sunucusuna bağlanarak Claude Code'un yeteneklerini geliştirebilir, mevcut kod tabanınız üzerinde anlamsal arama yapılmasını sağlayabilirsiniz.

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 Arama Kullanma

TOOL_STORE_DESCRIPTION ve TOOL_FIND_DESCRIPTION içinde belirtilen araç açıklamaları, Claude Code'a MCP sunucusunun nasıl kullanılacağı konusunda rehberlik eder. Yukarıda sağlananlar örnektir ve belirli kullanım durumunuz için özelleştirilmesi gerekebilir. Ancak, Claude Code zaten şunları yapabilmelidir:

Kod parçacıklarını açıklamalarla saklamak için qdrant-store aracını kullanın.
Doğal dil kullanarak ilgili kod parçacıklarını aramak için qdrant-find aracını kullanın.

MCP sunucusunu Geliştirme Modunda Çalıştırma

MCP sunucusu, mcp dev komutu kullanılarak geliştirme modunda çalıştırılabilir. Bu, sunucuyu başlatır ve tarayıcınızda MCP denetçisini açar.

COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py

VS Code ile kullanma

Tek tıklamayla kurulum için aşağıdaki kurulum düğmelerinden birine tıklayın:

Manuel Kurulum

VS Code'da Kullanıcı Ayarları (JSON) dosyanıza aşağıdaki JSON bloğunu ekleyin. Bunu Ctrl + Shift + P tuşuna basarak ve Preferences: Open User Settings (JSON) yazarak yapabilirsiniz.

{
  "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}"
        }
      }
    }
  }
}

Veya 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çerikle 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 içinde ş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 iyileştirilebileceğine dair önerileriniz varsa veya bir hata bildirmek istiyorsanız, bir sorun açın! Tüm katkıları memnuniyetle karşılıyoruz.

`mcp-server-qdrant` yerel olarak test etme

MCP denetçisi, MCP sunucularını test etmek ve hata ayıklamak için bir geliştirici aracıdır. Hem bir istemci kullanıcı arayüzünü (varsayılan bağlantı noktası 5173) hem de bir MCP proxy sunucusunu (varsayılan bağlantı noktası 3000) çalıştırır. Denetçiyi kullanmak için istemci kullanıcı arayüzünü tarayıcınızda açın.

QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py

Başladıktan sonra, denetçi arayüzüne erişmek için tarayıcınızı http://localhost:5173 adresine açın.

Lisans

Bu MCP sunucusu Apache License 2.0 altında lisanslanmıştır. Bu, yazılımı Apache License 2.0'ın şartlarına ve koşullarına tabi olarak kullanmakta, değiştirmekte ve dağıtmakta özgür olduğunuz anlamına gelir. Daha fazla ayrıntı için lütfen proje deposundaki LICENSE dosyasına bakın.