Qdrant MCP Server

resmi

Qdrant vektör veritabanı kullanarak anlamsal arama.

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 zeka destekli bir IDE geliştiriyor olun, ister bir sohbet arayüzünü geliştiriyor olun, isterse özel yapay zeka iş akışları oluşturuyor olun, MCP, LLM'leri ihtiyaç duydukları bağlamla bağlamak için standartlaştırılmış bir yol sunar.

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ı tutmak ve geri almak için resmi bir Model Context Protocol sunucusu. Qdrant veritabanı ü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 bilgi
  - metadata (JSON): Saklanacak isteğe bağlı meta veriler
  - collection_name (string): Bilginin saklanacağı koleksiyonun adı. Varsayılan bir koleksiyon adı yoksa bu alan zorunludur. Varsayılan bir koleksiyon adı varsa, bu alan etkin değildir.
- Döndürür: Onay mesajı
qdrant-find
- Qdrant veritabanından ilgili bilgileri getirir
- Girdi:
  - query (string): Arama için kullanılacak sorgu
  - collection_name (string): Bilginin saklanacağı koleksiyonun adı. Varsayılan bir koleksiyon adı yoksa bu alan zorunludur. Varsayılan bir koleksiyon adı varsa, bu alan etkin değildir.
- Döndürür: Qdrant veritabanında saklanan bilgiler ayrı mesajlar olarak

Ortam Değişkenleri

Yapılandırma, ortam değişkenleri aracılığıyla yapılır. Tek komut satırı argümanı --transport olup, aktarım protokolünü seçmek için kullanılır.

[!NOTE] QDRANT_URL ve QDRANT_LOCAL_PATH aynı anda sağlanamaz.

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 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`	Saklama aracı için özel açıklama	Varsayılan için `settings.py` bölümüne bakın
`TOOL_FIND_DESCRIPTION`	Bulma aracı için özel açıklama	Varsayılan için `settings.py` bölümüne bakın
`QDRANT_SEARCH_LIMIT`	Aramadan döndürülecek maksimum 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'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 seviyesini ayarlar (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Hata ayıklama modunu etkinleştirir	`false`
`FASTMCP_SERVER_HOST`	Sunucunun bağlanacağı ana bilgisayar adresi	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Sunucunun çalışacağı port	`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	`[]`

[!NOTE] Sunucuya özgü 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 ö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

Aktarım Protokolleri

Sunucu, --transport bayrağı kullanılarak belirtilebilen farklı aktarım protokollerini destekler:

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

Desteklenen aktarım protokolleri:

stdio (varsayılan): Standart girdi/çıktı aktarımı, yalnızca yerel MCP istemcileri tarafından kullanılabilir
sse: Sunucu Tarafından Gönderilen Olaylar aktarımı, uzak istemciler için mükemmeldir
streamable-http: Akışkan HTTP aktarımı, uzak istemciler için mükemmeldir, SSE'den daha yenidir

Belirtilmezse varsayılan aktarım stdio şeklindedir.

SSE aktarımı kullanıldığında, sunucu belirtilen portu dinleyecek ve gelen bağlantıları bekleyecektir. Varsayılan port 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 oluşturmak 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

[!TIP] Lütfen sunucunun tüm ağ arayüzlerini dinlemesini sağlamak için FASTMCP_SERVER_HOST="0.0.0.0" ayarını yaptığımızı unutmayın. Bu, sunucuyu bir Docker konteynerinde çalıştırırken gereklidir.

Smithery Üzerinden Kurulum

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

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

Claude Desktop'ın 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şturacaktır.

Varsayılan olarak, sunucu anıları kodlamak için sentence-transformers/all-MiniLM-L6-v2 gömme modelini kullanacaktı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 Protocol için yerleşik destek sağlayan Cursor ve VS Code ile kullanabilirsiniz.

Cursor/Windsurf ile Kullanım

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, daha sonra SSE aktarım protokolünü kullanarak bu çalışan sunucuya işaret ederek MCP sunucusunu ayarlarınızda yapılandırabilirsiniz. Cursor'a bir MCP sunucusunun nasıl ekleneceğine dair açıklama Cursor belgelerinde bulunabilir. Cursor/Windsurf'ü yerel olarak çalıştırıyorsanız, aşağıdaki URL'yi kullanabilirsiniz:

http://localhost:8000/sse

[!TIP] Uzak bağlantıları destekleyebildiği için, Cursor/Windsurf'ü MCP sunucusuna bağlamanın tercih edilen yolu olarak SSE aktarımı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ı saklamak
Anlamsal aramaya dayalı olarak ilgili kod örneklerini getirmek
Geliştiricilerin belirli uygulamaları veya kullanım kalıplarını bulmasına yardımcı olmak

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 ve ardından aradığınızı tanımlayan doğal dil sorguları kullanarak arama yaparak doldurabilirsiniz.

[!NOTE] Yukarıda sağlanan araç açıklamaları örnektir ve özel 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 yüklediyseniz, ancak yine de Cursor ile çalışmasını sağlayamıyorsanız, lütfen aracı yeni bir kod parçacığı ürettiğinde MCP araçlarının her zaman kullanılması için Cursor kurallarını oluşturmayı düşünün. Belgeler veya diğer içerik türleri için MCP sunucusunu kullanmaktan kaçınmak amacıyla kuralları yalnızca belirli dosya türleri için çalışacak şekilde kısıtlayabilirsiniz.

Claude Code ile Kullanım

Bu MCP sunucusuna bağlayarak Claude Code'un yeteneklerini geliştirebilir, mevcut kod tabanınız üzerinde anlamsal arama yapabilirsiniz.

mcp-server-qdrant'ı Kurma

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 sunucusunun nasıl kullanılacağı konusunda rehberlik eder. Yukarıda sağlananlar örnektir ve özel kullanım durumunuz için özelleştirilmesi gerekebilir. Bununla birlikte, Claude Code zaten şunları yapabilmelidir:

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

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şlatacak ve MCP denetçisini tarayıcınızda açacaktır.

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 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şlarına basıp 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 ederseniz, bunun yerine bu 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 içinde bunu 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 konu (issue) açın! Her türlü katkıyı memnuniyetle karşılarız.

`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ü (varsayılan port 5173) hem de bir MCP proxy sunucusu (varsayılan port 3000) çalıştırır. Denetçiyi kullanmak için tarayıcınızda istemci kullanıcı arayüzünü açın.

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

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

Lisans

Bu MCP sunucusu Apache Lisansı 2.0 altında lisanslanmıştır. Bu, yazılımı Apache Lisansı 2.0 hüküm 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.