Qdrant MCP

resmi

Pencarian 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 query dalam bahasa alami dengan qdrant-find.
  • Pilih koleksi — Tentukan collection_name tertentu untuk setiap pemanggilan, atau tetapkan nilai default melalui COLLECTION_NAME.
  • Sesuaikan deskripsi alat — Sesuaikan TOOL_STORE_DESCRIPTION dan TOOL_FIND_DESCRIPTION untuk mengubah server menjadi alat pencarian cuplikan kode.
  • Mode hanya-baca — Aktifkan QDRANT_READ_ONLY untuk menonaktifkan penyimpanan dan hanya mengizinkan pengambilan.
  • Atur hasil — Batasi hasil pencarian dengan QDRANT_SEARCH_LIMIT dan pilih model embedding melalui EMBEDDING_MODEL.

Dokumentasi

mcp-server-qdrant: Server MCP Qdrant

smithery badge

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

  1. qdrant-store
    • Menyimpan informasi di basis data Qdrant
    • Input:
      • information (string): Informasi yang akan disimpan
      • metadata (JSON): Metadata opsional yang akan disimpan
      • collection_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
  2. qdrant-find
    • Mengambil informasi yang relevan dari basis data Qdrant
    • Input:
      • query (string): Kueri yang digunakan untuk pencarian
      • collection_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_URL dan QDRANT_LOCAL_PATH secara bersamaan.

NamaDeskripsiNilai Default
QDRANT_URLURL server QdrantNone
QDRANT_API_KEYKunci API untuk server QdrantNone
COLLECTION_NAMENama koleksi default yang akan digunakan.None
QDRANT_LOCAL_PATHJalur ke basis data Qdrant lokal (alternatif untuk QDRANT_URL)None
EMBEDDING_PROVIDERPenyedia embedding yang akan digunakan (saat ini hanya "fastembed" yang didukung)fastembed
EMBEDDING_MODELNama model embedding yang akan digunakansentence-transformers/all-MiniLM-L6-v2
TOOL_STORE_DESCRIPTIONDeskripsi khusus untuk alat storeLihat default di settings.py
TOOL_FIND_DESCRIPTIONDeskripsi khusus untuk alat findLihat default di settings.py
QDRANT_SEARCH_LIMITJumlah maksimum hasil yang dikembalikan dari pencarian10
QDRANT_READ_ONLYAktifkan 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 LingkunganDeskripsiNilai Default
FASTMCP_LOG_LEVELMengatur tingkat pencatatan log (DEBUG, INFO, WARNING, ERROR, CRITICAL)INFO
FASTMCP_DEBUGMengaktifkan mode debugfalse
FASTMCP_HOSTAlamat host untuk mengikat server (transportasi SSE dan HTTP)127.0.0.1
FASTMCP_PORTPort untuk menjalankan server (transportasi SSE dan HTTP)8000
FASTMCP_MASK_ERROR_DETAILSMenyembunyikan detail pengecualian dari pesan kesalahan alat yang dikirim ke klienfalse

[!NOTE] Sebelum versi 0.9.0, pengaturan ini menggunakan awalan FASTMCP_SERVER_, misalnya FASTMCP_SERVER_HOST. Nama lama FASTMCP_SERVER_HOST, FASTMCP_SERVER_PORT, dan FASTMCP_SERVER_DEBUG masih 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 lokal
  • sse: Transportasi Server-Sent Events, cocok untuk klien jarak jauh
  • streamable-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:

  1. Menyimpan cuplikan kode, dokumentasi, dan detail implementasi
  2. Mengambil contoh kode yang relevan berdasarkan pencarian semantik
  3. 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

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

  1. Menggunakan alat qdrant-store untuk menyimpan cuplikan kode beserta deskripsinya.
  2. Menggunakan alat qdrant-find untuk 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:

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

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.

Privasi dan dukungan