Qdrant MCP Server

resmi

Menerapkan lapisan memori semantik di atas mesin pencari vektor Qdrant

Dokumentasi

mcp-server-qdrant: Server MCP Qdrant

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

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

Gambaran Umum

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

Komponen

Alat

qdrant-store
- Menyimpan beberapa informasi di basis data Qdrant
- Masukan:
  - information (string): Informasi yang akan disimpan
  - metadata (JSON): Metadata opsional untuk disimpan
  - collection_name (string): Nama koleksi untuk menyimpan informasi. Bidang ini wajib diisi jika tidak ada nama koleksi default. Jika ada nama koleksi default, bidang ini tidak diaktifkan.
- Mengembalikan: Pesan konfirmasi
qdrant-find
- Mengambil informasi yang relevan dari basis data Qdrant
- Masukan:
  - query (string): Kueri yang digunakan untuk pencarian
  - collection_name (string): Nama koleksi untuk menyimpan informasi. Bidang ini wajib diisi jika tidak ada nama koleksi default. Jika ada nama koleksi default, bidang ini tidak diaktifkan.
- Mengembalikan: Informasi yang tersimpan 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 transport.

[!CATATAN] Anda tidak dapat menyediakan 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 basis data Qdrant lokal (alternatif untuk `QDRANT_URL`)	Tidak ada
`EMBEDDING_PROVIDER`	Penyedia embedding yang akan 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 penyimpanan	Lihat default di `settings.py`
`TOOL_FIND_DESCRIPTION`	Deskripsi kustom untuk alat pencarian	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 didasarkan pada FastMCP, ia juga mendukung semua variabel lingkungan FastMCP. Yang paling penting tercantum di bawah ini:

Variabel Lingkungan	Deskripsi	Nilai Default
`FASTMCP_LOG_LEVEL`	Atur level logging (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	`[]`

[!CATATAN] Pengaturan khusus server menggunakan prefiks FASTMCP_SERVER_. Ini dapat 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 protokol transport berbeda yang dapat ditentukan menggunakan flag --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, mungkin hanya 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 dari 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 mengatur FASTMCP_SERVER_HOST="0.0.0.0" untuk membuat server mendengarkan di semua antarmuka jaringan. Ini diperlukan saat menjalankan server dalam kontainer Docker.

Menginstal melalui Smithery

Untuk menginstal Server MCP Qdrant 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 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 secara otomatis membuat koleksi dengan nama yang ditentukan jika belum ada.

Secara default, server akan menggunakan model embedding sentence-transformers/all-MiniLM-L6-v2 untuk mengenkode 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 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 lebih 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 potongan kode, dokumentasi, dan detail implementasi
Mengambil contoh kode yang relevan berdasarkan pencarian semantik
Membantu pengembang menemukan implementasi atau pola penggunaan tertentu

Anda dapat mengisi basis data dengan menyimpan deskripsi bahasa alami dari potongan kode (dalam parameter information) bersama dengan kode aktual (dalam properti metadata.code), dan kemudian mencarinya menggunakan kueri bahasa alami yang menjelaskan apa yang Anda cari.

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

Jika Anda telah berhasil menginstal mcp-server-qdrant, tetapi masih tidak dapat membuatnya berfungsi dengan Cursor, mohon pertimbangkan untuk membuat aturan Cursor sehingga alat MCP selalu digunakan saat agen menghasilkan potongan kode baru. Anda dapat membatasi aturan untuk hanya 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 atas basis kode Anda yang ada.

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 server telah ditambahkan:
```
claude mcp list
```

Menggunakan Pencarian Kode Semantik di Claude Code

Deskripsi alat, yang ditentukan dalam TOOL_STORE_DESCRIPTION dan TOOL_FIND_DESCRIPTION, memandu Claude Code tentang cara menggunakan server MCP. Yang disediakan di atas adalah contoh dan mungkin perlu disesuaikan untuk kasus penggunaan spesifik Anda. Namun, Claude Code seharusnya sudah dapat:

Menggunakan alat qdrant-store untuk menyimpan potongan kode dengan deskripsi.
Menggunakan alat qdrant-find untuk mencari potongan 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 Pengaturan Pengguna (JSON) Anda di VS Code. Anda dapat melakukan ini 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}"
      }
    }
  }
}

Berkontribusi

Jika Anda memiliki saran tentang bagaimana mcp-server-qdrant dapat ditingkatkan, atau ingin melaporkan bug, buka isu! Kami akan senang menerima 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 Lisensi Apache 2.0. Artinya, Anda bebas menggunakan, memodifikasi, dan mendistribusikan perangkat lunak ini, dengan tunduk pada syarat dan ketentuan Lisensi Apache 2.0. Untuk detail lebih lanjut, silakan lihat berkas LICENSE di repositori proyek.