Qdrant MCP

chính thức

Tì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?

Sử dụng Qdrant như một lớp bộ nhớ ngữ nghĩa cho trợ lý AI của bạn, cho phép nó lưu trữ và truy xuất thông tin theo ý nghĩa thay vì từ khóa chính xác.

Lưu trữ ký ức ngữ nghĩa — Yêu cầu trợ lý của bạn lưu thông tin với siêu dữ liệu tùy chọn vào Qdrant qua qdrant-store để truy xuất sau này.
Truy xuất ký ức liên quan — Sử dụng qdrant-find để tìm kiếm thông tin đã lưu bằng truy vấn ngôn ngữ tự nhiên và nhận kết quả khớp.
Xây dựng thư viện đoạn mã — Lưu trữ các đoạn mã kèm mô tả và truy xuất chúng theo ngữ nghĩa, như được minh họa trong các thiết lập Cursor và Claude Code.
Nhắm mục tiêu bộ sưu tập cụ thể — Lưu trữ hoặc tìm kiếm trong một bộ sưu tập có tên qua collection_name, hoặc dựa vào mặc định được đặt bởi COLLECTION_NAME.

Tài liệu

mcp-server-qdrant: Một máy chủ Qdrant MCP

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à các nguồn dữ liệu cùng công cụ bên ngoài. Dù bạn đang xây dựng một IDE hỗ trợ AI, nâng cấp giao diện trò chuyện, hay tạo các quy trình AI tùy chỉnh, MCP cung cấp một cách chuẩn hóa để kết nối LLM với bối cảnh mà chúng cần.

Kho lưu trữ này là một ví dụ về cách tạo một máy chủ MCP cho Qdrant, một công cụ tìm kiếm vector.

Tổng quan

Một máy chủ Model Context Protocol chính thức để lưu trữ và truy xuất ký ức trong công cụ tìm kiếm vector Qdrant. Nó hoạt động như một lớp bộ nhớ ngữ nghĩa trên nền tảng cơ sở dữ liệu Qdrant.

Các thành phần

Các công cụ

qdrant-store
- Lưu trữ một số thông tin trong cơ sở dữ liệu Qdrant
- Đầu vào:
  - information (chuỗi): Thông tin cần lưu trữ
  - metadata (JSON): Siêu dữ liệu tùy chọn để lưu trữ
  - collection_name (chuỗi): Tên của collection để 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 không được kích hoạ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 (chuỗi): Truy vấn để sử dụng cho việc tìm kiếm
  - collection_name (chuỗi): Tên của collection để 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 không được kích hoạt.
- Trả về: Thông tin được lưu trữ trong cơ sở dữ liệu Qdrant dưới dạng các thông điệp 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, được sử dụng để chọn giao thức truyền tải.

[!NOTE] Bạn không thể cung cấp cả QDRANT_URL và QDRANT_LOCAL_PATH cùng một lúc.

Tên	Mô tả	Giá trị mặc định
`QDRANT_URL`	URL của máy chủ Qdrant	Không có
`QDRANT_API_KEY`	Khóa API cho máy chủ Qdrant	Không có
`COLLECTION_NAME`	Tên của collection mặc định để sử dụng.	Không có
`QDRANT_LOCAL_PATH`	Đường dẫn đến cơ sở dữ liệu Qdrant cục bộ (thay thế cho `QDRANT_URL`)	Không có
`EMBEDDING_PROVIDER`	Nhà cung cấp embedding để sử dụng (hiện chỉ hỗ trợ "fastembed")	`fastembed`
`EMBEDDING_MODEL`	Tên của mô hình embedding để sử dụng	`sentence-transformers/all-MiniLM-L6-v2`
`TOOL_STORE_DESCRIPTION`	Mô tả tùy chỉnh cho công cụ store	Xem mặc định trong `settings.py`
`TOOL_FIND_DESCRIPTION`	Mô tả tùy chỉnh cho công cụ find	Xem 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ó cũng hỗ trợ tất cả các biến môi trường của FastMCP. Các biến quan trọng nhất được liệt kê dưới đây:

Biến môi trường	Mô tả	Giá trị mặc định
`FASTMCP_LOG_LEVEL`	Đặt mức ghi log (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Bật chế độ gỡ lỗi	`false`
`FASTMCP_SERVER_HOST`	Địa chỉ host để liên kết máy chủ	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Cổng để chạy máy chủ	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Hành vi cho các tài nguyên trùng lặp (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Hành vi cho các công cụ trùng lặp (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Hành vi cho các prompt trùng lặp (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_DEPENDENCIES`	Danh sách các phụ thuộc để cài đặt trong môi trường máy chủ	`[]`

[!NOTE] Các cài đặt cụ thể của máy chủ sử dụng tiền tố FASTMCP_SERVER_. Điều này có thể thay đổi trong các phiên bản tương lai.

Cài đặt

Sử dụng uvx

Khi sử dụng uvx, không cần cài đặt cụ thể nào để 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ợ các giao thức truyền tải khác nhau có thể được 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): Truyền tải qua luồng chuẩn vào/ra, chỉ có thể được sử dụng bởi các máy khách MCP cục bộ
sse: Truyền tải Server-Sent Events, hoàn hảo cho các máy khách từ xa
streamable-http: Truyền tải HTTP có thể phát trực tuyến, hoàn hảo cho các máy khách từ xa, mới hơn SSE

Giao thức truyền tải mặc định là stdio nếu không được chỉ định.

Khi sử dụng truyền tải SSE, máy chủ sẽ lắng nghe trên cổng được chỉ định và chờ các kết nối đến. Cổng mặc định là 8000, tuy nhiên có thể được thay đổi bằng biến môi trường FASTMCP_SERVER_PORT.

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

Sử dụng Docker

Một Dockerfile có sẵn để 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_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] Xin lưu ý rằng chúng tôi đặt FASTMCP_SERVER_HOST="0.0.0.0" để máy chủ lắng nghe trên tất cả các giao diện mạng. Điều này là cần thiết khi chạy máy chủ trong một container Docker.

Cài đặt qua Smithery

Để cài đặt Qdrant MCP Server cho Claude Desktop tự động qua Smithery:

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

Cấu hình thủ công Claude Desktop

Để 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" của claude_desktop_config.json của bạn:

{
  "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 một collection với tên được chỉ định nếu nó 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ỉ có các mô hình FastEmbed được hỗ trợ.

Hỗ trợ cho các công cụ khác

Máy chủ MCP này có thể được sử dụng với bất kỳ máy khách nào tương thích MCP. Ví dụ, bạn có thể sử dụng nó với Cursor và VS Code, các công cụ này cung cấp 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 để hoạt động như một 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

Trong Cursor/Windsurf, bạn có thể cấu hình máy chủ MCP trong cài đặt của mình bằng cách trỏ đến máy chủ đang chạy này bằng giao thức truyền tải SSE. Hướng dẫn về cách thêm máy chủ MCP vào Cursor có thể được tìm thấy trong tài liệu Cursor. Nếu bạn đang chạy Cursor/Windsurf cục bộ, bạn có thể sử dụng URL sau:

http://localhost:8000/sse

[!TIP] Chúng tôi khuyên dùng truyền tải SSE như một cách ưu tiên để kết nối Cursor/Windsurf với máy chủ MCP, vì nó có thể hỗ trợ các kết nối từ xa. Điều này giúp dễ dàng chia sẻ máy chủ với nhóm của bạn hoặc sử dụng nó trong môi trường đám mây.

Cấu hình này biến máy chủ Qdrant MCP thành một công cụ tìm kiếm mã chuyên dụng 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 triển khai cụ thể hoặc mẫu sử dụng

Bạn có thể điền dữ liệu vào cơ sở dữ liệu bằng cách lưu trữ mô tả ngôn ngữ tự nhiên của 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 chúng bằng các truy vấn ngôn ngữ tự nhiên mô tả những gì bạn đang tìm kiếm.

[!NOTE] Các mô tả công cụ đượ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. Hãy cân nhắc điều chỉnh các mô tả để phù hợp hơn với quy trình làm việc của nhóm bạn và các loại đoạn mã cụ thể bạn muốn lưu trữ và truy xuất.

Nếu bạn đã cài đặt mcp-server-qdrant thành công, nhưng vẫn không thể làm cho nó hoạt động với Cursor, vui lòng cân nhắc tạo quy tắc Cursor để các công cụ MCP luôn được sử dụng khi agent tạo một đoạn mã mới. Bạn có thể giới hạn các quy tắc chỉ hoạt độ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 nó với máy chủ MCP này, cho phép tìm kiếm ngữ nghĩa trên mã nguồn 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

Các 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 sẽ 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

Máy chủ MCP có thể được chạy ở chế độ phát triển bằng lệnh mcp dev. Điều này sẽ khởi động máy chủ và mở trình kiểm tra MCP 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 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) của bạn trong VS Code. Bạn có thể thực hiện điều này bằng cách nhấn Ctrl + Shift + P và gõ 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 bạn thích 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 một tệp .vscode/mcp.json trong workspace của mình 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}"
      }
    }
  }
}

Đối với cấu hình workspace với Docker, sử dụng cấu hình 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 về cách cải thiện mcp-server-qdrant, hoặc muốn báo cáo lỗi, hãy mở một issue! Chúng tôi rất hoan nghênh mọi đóng góp.

Kiểm thử `mcp-server-qdrant` cục bộ

Trình kiểm tra MCP là một công cụ dành cho nhà phát triển để kiểm thử và gỡ lỗi các máy chủ MCP. Nó chạy cả giao diện người dùng máy khách (cổng mặc định 5173) và một 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 của bạn để sử dụng trình kiểm tra.

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 của bạn đến http://localhost:5173 để truy cập giao diện trình kiểm tra.

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.