Qdrant MCP

resmi

Pencarian semantik menggunakan basis data vektor Qdrant.

Apa yang bisa Anda lakukan dengan Qdrant MCP?

Gunakan Qdrant sebagai lapisan memori semantik untuk asisten AI Anda, sehingga dapat menyimpan dan mengambil informasi berdasarkan makna, bukan kata kunci yang persis.

Simpan memori semantik — Minta asisten Anda untuk menyimpan informasi dengan metadata opsional ke Qdrant melalui qdrant-store untuk diambil kemudian.
Ambil memori yang relevan — Gunakan qdrant-find untuk mencari informasi yang tersimpan dengan kueri bahasa alami dan dapatkan hasil yang cocok.
Bangun pustaka cuplikan kode — Simpan cuplikan kode dengan deskripsi dan ambil secara semantik, seperti yang ditunjukkan pada pengaturan Cursor dan Claude Code.
Targetkan koleksi tertentu — Simpan atau cari dalam koleksi bernama melalui collection_name, atau gunakan bawaan yang ditetapkan oleh COLLECTION_NAME.

Dokumentasi

mcp-server-qdrant: Server MCP Qdrant

Model Context Protocol (MCP) adalah protokol terbuka yang memungkinkan integrasi mulus antara aplikasi LLM dan sumber data serta alat eksternal. Baik Anda sedang membangun IDE bertenaga AI, meningkatkan antarmuka chat, atau membuat alur kerja AI kustom, MCP menyediakan cara terstandar untuk menghubungkan LLM dengan konteks yang mereka butuhkan.

Repositori ini adalah contoh cara membuat server MCP untuk Qdrant, mesin pencari vektor.

Ikhtisar

Server Model Context Protocol resmi untuk menyimpan dan mengambil memori di mesin pencari vektor Qdrant. Ini bertindak sebagai lapisan memori semantik di atas database Qdrant.

Komponen

Alat

qdrant-store
- Menyimpan beberapa informasi di database Qdrant
- Masukan:
  - information (string): Informasi yang akan disimpan
  - metadata (JSON): Metadata opsional yang akan disimpan
  - collection_name (string): Nama koleksi tempat menyimpan informasi. Kolom ini wajib diisi jika tidak ada nama koleksi default. Jika ada nama koleksi default, kolom ini tidak aktif.
- Mengembalikan: Pesan konfirmasi
qdrant-find
- Mengambil informasi yang relevan dari database Qdrant
- Masukan:
  - query (string): Kueri yang digunakan untuk pencarian
  - collection_name (string): Nama koleksi tempat menyimpan informasi. Kolom ini wajib diisi jika tidak ada nama koleksi default. Jika ada nama koleksi default, kolom ini tidak aktif.
- Mengembalikan: Informasi yang disimpan di database Qdrant sebagai pesan terpisah

Variabel Lingkungan

Konfigurasi dilakukan melalui variabel lingkungan. Satu-satunya argumen baris perintah adalah --transport, digunakan untuk memilih protokol transport.

[!NOTE] Anda tidak dapat memberikan QDRANT_URL dan QDRANT_LOCAL_PATH secara bersamaan.

Nama	Deskripsi	Nilai Default
`QDRANT_URL`	URL server Qdrant	Tidak ada
`QDRANT_API_KEY`	Kunci API untuk server Qdrant	Tidak ada
`COLLECTION_NAME`	Nama koleksi default yang akan digunakan.	Tidak ada
`QDRANT_LOCAL_PATH`	Jalur ke database Qdrant lokal (alternatif untuk `QDRANT_URL`)	Tidak ada
`EMBEDDING_PROVIDER`	Penyedia embedding yang digunakan (saat ini hanya "fastembed" yang didukung)	`fastembed`
`EMBEDDING_MODEL`	Nama model embedding yang akan digunakan	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	Deskripsi kustom untuk alat store	Lihat default di `settings.py`
`TOOL_FIND_DESCRIPTION`	Deskripsi kustom untuk alat find	Lihat default di `settings.py`
`QDRANT_SEARCH_LIMIT`	Jumlah maksimum hasil yang dikembalikan dari pencarian	`10`
`QDRANT_READ_ONLY`	Aktifkan mode hanya-baca (menonaktifkan alat `qdrant-store`)	`false`

Variabel Lingkungan FastMCP

Karena mcp-server-qdrant berbasis FastMCP, ia juga mendukung semua variabel lingkungan FastMCP. Yang paling penting tercantum di bawah ini:

Variabel Lingkungan	Deskripsi	Nilai Default
`FASTMCP_LOG_LEVEL`	Atur tingkat pencatatan (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Aktifkan mode debug	`false`
`FASTMCP_SERVER_HOST`	Alamat host untuk mengikat server	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Port untuk menjalankan server	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Perilaku untuk sumber daya duplikat (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Perilaku untuk alat duplikat (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Perilaku untuk prompt duplikat (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	Daftar dependensi yang akan diinstal di lingkungan server	`[]`

[!NOTE] Pengaturan khusus server menggunakan awalan FASTMCP_SERVER_. Ini mungkin berubah di versi mendatang.

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 Transport

Server mendukung berbagai protokol transport yang dapat ditentukan menggunakan bendera --transport:

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

Protokol transport yang didukung:

stdio (default): Transport input/output standar, hanya dapat digunakan oleh klien MCP lokal
sse: Transport Server-Sent Events, sempurna untuk klien jarak jauh
streamable-http: Transport HTTP Streamable, sempurna untuk klien jarak jauh, lebih baru daripada SSE

Transport default adalah stdio jika tidak ditentukan.

Saat transport SSE digunakan, server akan mendengarkan pada port yang ditentukan dan menunggu koneksi masuk. Port default adalah 8000, namun dapat diubah menggunakan variabel lingkungan FASTMCP_SERVER_PORT.

QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_SERVER_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_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] Harap dicatat bahwa kami menetapkan FASTMCP_SERVER_HOST="0.0.0.0" untuk membuat server mendengarkan di semua antarmuka jaringan. Ini diperlukan saat menjalankan server di dalam kontainer Docker.

Menginstal melalui Smithery

Untuk menginstal Qdrant MCP Server untuk Claude Desktop secara otomatis 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:

{
  "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 secara otomatis membuat koleksi dengan nama yang ditentukan jika tidak ada.

Secara default, server akan menggunakan model embedding sentence-transformers/all-MiniLM-L6-v2 untuk menyandikan memori. Untuk saat ini, hanya model FastEmbed yang didukung.

Dukungan untuk alat lainnya

Server MCP ini dapat digunakan dengan klien yang kompatibel dengan MCP mana pun. 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 untuk bekerja 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 Anda dengan menunjuk ke server yang berjalan ini menggunakan protokol transport SSE. Deskripsi tentang cara 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 transport SSE sebagai cara yang disukai untuk menghubungkan Cursor/Windsurf ke server MCP, karena dapat mendukung koneksi jarak jauh. Itu memudahkan untuk berbagi server dengan tim Anda atau menggunakannya di lingkungan cloud.

Konfigurasi ini mengubah server MCP Qdrant menjadi alat pencarian kode khusus yang dapat:

Menyimpan cuplikan kode, dokumentasi, dan detail implementasi
Mengambil contoh kode yang relevan berdasarkan pencarian semantik
Membantu pengembang menemukan implementasi atau pola penggunaan tertentu

Anda dapat mengisi database dengan menyimpan deskripsi bahasa alami dari cuplikan kode (di parameter information) bersama dengan kode aktual (di properti metadata.code), lalu mencari mereka menggunakan kueri bahasa alami yang menjelaskan apa yang Anda cari.

[!NOTE] Deskripsi alat yang disediakan di atas hanyalah contoh dan mungkin perlu disesuaikan untuk kasus penggunaan spesifik Anda. Pertimbangkan menyesuaikan deskripsi agar lebih cocok dengan alur kerja tim Anda dan jenis cuplikan kode spesifik yang ingin Anda simpan dan ambil.

Jika Anda telah berhasil menginstal mcp-server-qdrant, tetapi masih tidak dapat membuatnya bekerja dengan Cursor, harap pertimbangkan untuk membuat aturan Cursor sehingga alat MCP selalu digunakan saat agen menghasilkan cuplikan kode baru. Anda dapat membatasi aturan hanya untuk bekerja pada jenis file tertentu, untuk menghindari penggunaan server MCP untuk dokumentasi atau jenis konten lainnya.

Menggunakan dengan Claude Code

Anda dapat meningkatkan kemampuan Claude Code dengan menghubungkannya ke server MCP ini, memungkinkan pencarian semantik di basis kode yang Anda miliki.

Menyiapkan mcp-server-qdrant

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

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. Yang disediakan di atas hanyalah contoh dan mungkin perlu disesuaikan untuk kasus penggunaan spesifik Anda. Namun, Claude Code seharusnya sudah dapat:

Menggunakan alat qdrant-store untuk menyimpan cuplikan kode dengan deskripsi.
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. Ini akan memulai server dan membuka inspektur MCP di browser Anda.

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

Menggunakan dengan VS Code

Untuk instalasi satu klik, klik salah satu tombol instal di bawah ini:

Instalasi Manual

Tambahkan blok JSON berikut ke file User Settings (JSON) Anda di VS Code. Anda dapat melakukannya dengan menekan Ctrl + Shift + P dan 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 sebagai gantinya:

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

Alternatifnya, Anda dapat membuat file .vscode/mcp.json di ruang kerja Anda 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 tentang bagaimana mcp-server-qdrant dapat ditingkatkan, atau ingin melaporkan bug, buka sebuah isu! Kami menyambut semua dan setiap kontribusi.

Menguji `mcp-server-qdrant` secara lokal

Inspektur MCP adalah alat pengembang untuk menguji dan men-debug server MCP. Ini menjalankan UI klien (port default 5173) dan server proxy MCP (port default 3000). Buka UI klien di browser Anda untuk menggunakan inspektur.

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

Setelah dimulai, buka browser Anda ke http://localhost:5173 untuk mengakses antarmuka inspektur.

Lisensi

Server MCP ini dilisensikan di bawah Apache License 2.0. Ini berarti Anda bebas untuk menggunakan, memodifikasi, dan mendistribusikan perangkat lunak ini, sesuai dengan syarat dan ketentuan Apache License 2.0. Untuk detail lebih lanjut, silakan lihat file LICENSE di repositori proyek.