Qdrant MCP
chính thứcTìm kiếm ngữ nghĩa sử dụng cơ sở dữ liệu vector Qdrant.
Bạn có thể làm gì với Qdrant MCP?
- Lưu trữ ký ức — Yêu cầu trợ lý lưu thông tin, kèm siêu dữ liệu tùy chọn, vào bộ sưu tập Qdrant bằng
qdrant-store. - Tìm kiếm ngữ nghĩa — Truy xuất thông tin liên quan đã lưu bằng
queryngôn ngữ tự nhiên vớiqdrant-find. - Chọn bộ sưu tập — Chỉ định
collection_namecho từng lệnh gọi hoặc đặt giá trị mặc định bằngCOLLECTION_NAME. - Tùy chỉnh mô tả công cụ — Điều chỉnh
TOOL_STORE_DESCRIPTIONvàTOOL_FIND_DESCRIPTIONđể biến máy chủ thành công cụ tìm kiếm đoạn mã. - Chế độ chỉ đọc — Bật
QDRANT_READ_ONLYđể tắt chức năng lưu trữ và chỉ cho phép truy xuất. - Tinh chỉnh kết quả — Giới hạn số kết quả tìm kiếm bằng
QDRANT_SEARCH_LIMITvà chọn mô hình embedding quaEMBEDDING_MODEL.
Tài liệu
mcp-server-qdrant: Máy chủ MCP Qdrant
Model Context Protocol (MCP) là một giao thức mở cho phép tích hợp liền mạch giữa các ứng dụng LLM với nguồn dữ liệu và công cụ bên ngoài. Dù bạn đang xây dựng một IDE hỗ trợ AI, nâng cao giao diện trò chuyện hay tạo quy trình AI tùy chỉnh, MCP cung cấp một cách thức tiêu chuẩn để kết nối LLM với ngữ cảnh mà chúng cần.
Kho lưu trữ này là ví dụ về cách tạo máy chủ MCP cho Qdrant, một công cụ tìm kiếm vector.
Tổng quan
Máy chủ Model Context Protocol chính thức dùng để lưu trữ và truy xuất ký ức trong công cụ tìm kiếm vector Qdrant. Máy chủ này đóng vai trò là một lớp bộ nhớ ngữ nghĩa trên cơ sở dữ liệu Qdrant.
Thành phần
Công cụ
qdrant-store- Lưu trữ thông tin trong cơ sở dữ liệu Qdrant
- Đầu vào:
information(string): Thông tin cần lưu trữmetadata(JSON): Siêu dữ liệu tùy chọn cần lưu trữcollection_name(string): Tên collection dùng để lưu trữ thông tin. Trường này là bắt buộc nếu không có tên collection mặc định. Nếu có tên collection mặc định, trường này sẽ không được bật.
- Trả về: Thông báo xác nhận
qdrant-find- Truy xuất thông tin liên quan từ cơ sở dữ liệu Qdrant
- Đầu vào:
query(string): Truy vấn dùng để tìm kiếmcollection_name(string): Tên collection dùng để lưu trữ thông tin. Trường này là bắt buộc nếu không có tên collection mặc định. Nếu có tên collection mặc định, trường này sẽ không được bật.
- Trả về: Thông tin được lưu trong cơ sở dữ liệu Qdrant dưới dạng các thông báo riêng biệt
Biến môi trường
Cấu hình được thực hiện thông qua các biến môi trường. Đối số dòng lệnh duy nhất là --transport, dùng để chọn giao thức truyền tải.
[!NOTE] Không thể đồng thời cung cấp cả
QDRANT_URLvàQDRANT_LOCAL_PATH.
| Tên | Mô tả | Giá trị mặc định |
|---|---|---|
QDRANT_URL | URL của máy chủ Qdrant | None |
QDRANT_API_KEY | Khóa API của máy chủ Qdrant | None |
COLLECTION_NAME | Tên collection mặc định sẽ sử dụng. | None |
QDRANT_LOCAL_PATH | Đường dẫn đến cơ sở dữ liệu Qdrant cục bộ (thay thế cho QDRANT_URL) | None |
EMBEDDING_PROVIDER | Nhà cung cấp embedding sẽ sử dụng (hiện chỉ hỗ trợ "fastembed") | fastembed |
EMBEDDING_MODEL | Tên mô hình embedding sẽ sử dụng | sentence-transformers/all-MiniLM-L6-v2 |
TOOL_STORE_DESCRIPTION | Mô tả tùy chỉnh cho công cụ store | Xem giá trị mặc định trong settings.py |
TOOL_FIND_DESCRIPTION | Mô tả tùy chỉnh cho công cụ find | Xem giá trị mặc định trong settings.py |
QDRANT_SEARCH_LIMIT | Số lượng kết quả tối đa trả về từ tìm kiếm | 10 |
QDRANT_READ_ONLY | Bật chế độ chỉ đọc (vô hiệu hóa công cụ qdrant-store) | false |
Biến môi trường FastMCP
Vì mcp-server-qdrant dựa trên FastMCP nên cũng hỗ trợ tất cả biến môi trường FastMCP. Các biến
quan trọng nhất được liệt kê bên dưới:
| Biến môi trường | Mô tả | Giá trị mặc định |
|---|---|---|
FASTMCP_LOG_LEVEL | Đặt mức ghi nhật ký (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
FASTMCP_DEBUG | Bật chế độ gỡ lỗi | false |
FASTMCP_HOST | Địa chỉ máy chủ sẽ liên kết (giao thức truyền tải SSE và HTTP) | 127.0.0.1 |
FASTMCP_PORT | Cổng chạy máy chủ (giao thức truyền tải SSE và HTTP) | 8000 |
FASTMCP_MASK_ERROR_DETAILS | Ẩn chi tiết ngoại lệ khỏi thông báo lỗi của công cụ gửi đến máy khách | false |
[!NOTE] Trước phiên bản 0.9.0, các cài đặt này sử dụng tiền tố
FASTMCP_SERVER_, ví dụFASTMCP_SERVER_HOST. Các tên cũFASTMCP_SERVER_HOST,FASTMCP_SERVER_PORTvàFASTMCP_SERVER_DEBUGvẫn hoạt động nhưng đã lỗi thời và sẽ bị xóa trong bản phát hành tương lai. Nếu cả hai tên đều được đặt, tên mới sẽ được ưu tiên.
Cài đặt
Sử dụng uvx
Khi sử dụng uvx, không cần cài đặt cụ thể để chạy trực tiếp mcp-server-qdrant.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
EMBEDDING_MODEL="sentence-transformers/all-MiniLM-L6-v2" \
uvx mcp-server-qdrant
Giao thức truyền tải
Máy chủ hỗ trợ nhiều giao thức truyền tải khác nhau, có thể chỉ định bằng cờ --transport:
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
uvx mcp-server-qdrant --transport sse
Các giao thức truyền tải được hỗ trợ:
stdio(mặc định): Giao thức truyền tải đầu vào/đầu ra tiêu chuẩn, có thể chỉ được dùng bởi các máy khách MCP cục bộsse: Giao thức truyền tải Server-Sent Events, phù hợp cho máy khách từ xastreamable-http: Giao thức truyền tải Streamable HTTP, phù hợp cho máy khách từ xa và mới hơn SSE
Nếu không chỉ định, giao thức truyền tải mặc định là stdio.
Khi sử dụng giao thức truyền tải SSE, máy chủ sẽ lắng nghe trên cổng được chỉ định và chờ kết nối đến. Cổng mặc định
là 8000, nhưng có thể thay đổi bằng biến môi trường FASTMCP_PORT.
QDRANT_URL="http://localhost:6333" \
COLLECTION_NAME="my-collection" \
FASTMCP_PORT=1234 \
uvx mcp-server-qdrant --transport sse
Sử dụng Docker
Có sẵn Dockerfile để xây dựng và chạy máy chủ 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] Lưu ý rằng chúng tôi đặt
FASTMCP_HOST="0.0.0.0"để máy chủ lắng nghe trên tất cả giao diện mạng. Điều này cần thiết khi chạy máy chủ trong vùng chứa Docker.
Cài đặt qua Smithery
Để tự động cài đặt Qdrant MCP Server cho Claude Desktop thông qua Smithery:
npx @smithery/cli install mcp-server-qdrant --client claude
Cấu hình Claude Desktop thủ công
Để sử dụng máy chủ này với ứng dụng Claude Desktop, hãy thêm cấu hình sau vào phần "mcpServers" trong
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"
}
}
}
Đối với chế độ Qdrant cục bộ:
{
"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"
}
}
}
Máy chủ MCP này sẽ tự động tạo collection với tên được chỉ định nếu collection đó chưa tồn tại.
Theo mặc định, máy chủ sẽ sử dụng mô hình embedding sentence-transformers/all-MiniLM-L6-v2 để mã hóa ký ức.
Hiện tại, chỉ hỗ trợ các mô hình FastEmbed.
Hỗ trợ các công cụ khác
Máy chủ MCP này có thể được sử dụng với mọi máy khách tương thích MCP. Ví dụ: bạn có thể dùng máy chủ này với Cursor và VS Code, vốn có hỗ trợ tích hợp cho Model Context Protocol.
Sử dụng với Cursor/Windsurf
Bạn có thể cấu hình máy chủ MCP này làm công cụ tìm kiếm mã cho Cursor hoặc Windsurf bằng cách tùy chỉnh mô tả công cụ:
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
Sau đó, trong Cursor/Windsurf, bạn có thể cấu hình máy chủ MCP trong phần cài đặt bằng cách trỏ đến máy chủ đang chạy này và sử dụng giao thức truyền tải SSE. Hướng dẫn thêm máy chủ MCP vào Cursor có trong tài liệu Cursor. Nếu bạn đang chạy Cursor/Windsurf cục bộ, có thể sử dụng URL sau:
http://localhost:8000/sse
[!TIP] Chúng tôi khuyến nghị sử dụng giao thức truyền tải SSE để kết nối Cursor/Windsurf với máy chủ MCP, vì giao thức này hỗ trợ kết nối từ xa. Nhờ đó, bạn có thể dễ dàng chia sẻ máy chủ với nhóm hoặc sử dụng trong môi trường đám mây.
Cấu hình này biến máy chủ MCP Qdrant thành một công cụ tìm kiếm mã chuyên biệt có thể:
- Lưu trữ các đoạn mã, tài liệu và chi tiết triển khai
- Truy xuất các ví dụ mã liên quan dựa trên tìm kiếm ngữ nghĩa
- Giúp nhà phát triển tìm các cách triển khai hoặc mẫu sử dụng cụ thể
Bạn có thể đưa dữ liệu vào cơ sở dữ liệu bằng cách lưu trữ mô tả bằng ngôn ngữ tự nhiên về các đoạn mã (trong tham số information)
cùng với mã thực tế (trong thuộc tính metadata.code), sau đó tìm kiếm bằng các truy vấn ngôn ngữ tự nhiên
mô tả nội dung bạn đang tìm.
[!NOTE] Các mô tả công cụ ở trên chỉ là ví dụ và có thể cần được tùy chỉnh cho trường hợp sử dụng cụ thể của bạn. Hãy cân nhắc điều chỉnh mô tả để phù hợp hơn với quy trình làm việc của nhóm và các loại đoạn mã cụ thể mà bạn muốn lưu trữ và truy xuất.
Nếu bạn đã cài đặt thành công mcp-server-qdrant nhưng vẫn không thể sử dụng với Cursor, hãy cân nhắc tạo quy tắc Cursor để các công cụ MCP luôn được sử dụng khi
tác nhân tạo đoạn mã mới. Bạn có thể giới hạn quy tắc chỉ áp dụng cho một số loại tệp nhất định để tránh sử dụng
máy chủ MCP cho tài liệu hoặc các loại nội dung khác.
Sử dụng với Claude Code
Bạn có thể nâng cao khả năng của Claude Code bằng cách kết nối với máy chủ MCP này, cho phép tìm kiếm ngữ nghĩa trên cơ sở mã hiện có của bạn.
Thiết lập mcp-server-qdrant
-
Thêm máy chủ MCP vào 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 -
Xác minh máy chủ đã được thêm:
claude mcp list
Sử dụng tìm kiếm mã ngữ nghĩa trong Claude Code
Mô tả công cụ, được chỉ định trong TOOL_STORE_DESCRIPTION và TOOL_FIND_DESCRIPTION, hướng dẫn Claude Code cách sử dụng
máy chủ MCP. Các mô tả được cung cấp ở trên chỉ là ví dụ và có thể cần được tùy chỉnh cho trường hợp sử dụng cụ thể của bạn. Tuy nhiên,
Claude Code đã có thể:
- Sử dụng công cụ
qdrant-stoređể lưu trữ các đoạn mã kèm mô tả. - Sử dụng công cụ
qdrant-findđể tìm kiếm các đoạn mã liên quan bằng ngôn ngữ tự nhiên.
Chạy máy chủ MCP ở chế độ phát triển
Có thể chạy máy chủ MCP ở chế độ phát triển bằng lệnh mcp dev. Lệnh này sẽ khởi động máy chủ và mở MCP
inspector trong trình duyệt của bạn.
COLLECTION_NAME=mcp-dev fastmcp dev src/mcp_server_qdrant/server.py
Sử dụng với VS Code
Để cài đặt chỉ bằng một cú nhấp chuột, hãy nhấp vào một trong các nút cài đặt bên dưới:
Cài đặt thủ công
Thêm khối JSON sau vào tệp User Settings (JSON) trong VS Code. Bạn có thể thực hiện việc này bằng cách nhấn Ctrl + Shift + P rồi nhập 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}"
}
}
}
}
}
Hoặc nếu muốn sử dụng Docker, hãy thêm cấu hình này:
{
"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}"
}
}
}
}
}
Ngoài ra, bạn có thể tạo tệp .vscode/mcp.json trong không gian làm việc với nội dung sau:
{
"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}"
}
}
}
}
Để cấu hình không gian làm việc bằng Docker, hãy dùng nội dung này trong .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}"
}
}
}
}
Đóng góp
Nếu bạn có đề xuất cải thiện mcp-server-qdrant hoặc muốn báo lỗi, hãy mở một issue! Chúng tôi luôn hoan nghênh mọi đóng góp.
Kiểm thử mcp-server-qdrant cục bộ
MCP inspector là công cụ dành cho nhà phát triển để kiểm thử và gỡ lỗi các máy chủ MCP. Công cụ này chạy cả giao diện người dùng máy khách (cổng mặc định 5173) và máy chủ proxy MCP (cổng mặc định 3000). Mở giao diện người dùng máy khách trong trình duyệt để sử dụng inspector.
QDRANT_URL=":memory:" COLLECTION_NAME="test" \
fastmcp dev src/mcp_server_qdrant/server.py
Sau khi khởi động, hãy mở trình duyệt và truy cập http://localhost:5173 để dùng giao diện inspector.
Giấy phép
Máy chủ MCP này được cấp phép theo Apache License 2.0. Điều này có nghĩa là bạn được tự do sử dụng, sửa đổi và phân phối phần mềm, tuân theo các điều khoản và điều kiện của Apache License 2.0. Để biết thêm chi tiết, vui lòng xem tệp LICENSE trong kho lưu trữ dự án.