Qdrant MCP Server

chính thức

Semantic search using the Qdrant vector database.

Tài liệu

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

Giao thức Ngữ cảnh Mô hình (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 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 làm việc AI tùy chỉnh, MCP cung cấp một cách chuẩn hóa để kết nối LLM với ngữ cảnh chúng cần.

Kho lưu trữ này là một 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ủ Giao thức Ngữ cảnh Mô hình chính thức để lưu giữ 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 cơ sở dữ liệu Qdrant.

Thành phần

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 bộ sưu tập để lưu trữ thông tin. Trường này là bắt buộc nếu không có tên bộ sưu tập mặc định. Nếu có tên bộ sưu tập 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 tìm kiếm
  - collection_name (chuỗi): Tên của bộ sưu tập để lưu trữ thông tin. Trường này là bắt buộc nếu không có tên bộ sưu tập mặc định. Nếu có tên bộ sưu tập 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 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, được sử dụng để chọn giao thức truyền tải.

[!LƯU Ý] Bạn không thể cung cấp đồng thời cả QDRANT_URL và QDRANT_LOCAL_PATH.

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 bộ sưu tập 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ụ lưu trữ	Xem mặc định trong `settings.py`
`TOOL_FIND_DESCRIPTION`	Mô tả tùy chỉnh cho công cụ tìm kiếm	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 FastMCP. Những 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 nhật ký (DEBUG, INFO, WARNING, ERROR, CRITICAL)	`INFO`
`FASTMCP_SERVER_DEBUG`	Bật chế độ gỡ lỗi	`false`
`FASTMCP_SERVER_HOST`	Địa chỉ máy chủ để liên kết	`127.0.0.1`
`FASTMCP_SERVER_PORT`	Cổng để chạy máy chủ	`8000`
`FASTMCP_SERVER_ON_DUPLICATE_RESOURCES`	Hành vi cho tài nguyên trùng lặp (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_TOOLS`	Hành vi cho công cụ trùng lặp (warn, error, replace, ignore)	`warn`
`FASTMCP_SERVER_ON_DUPLICATE_PROMPTS`	Hành vi cho 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ủ	`[]`

[!LƯU Ý] Các cài đặt dành riêng cho 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ể để 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 đầu vào/đầu ra tiêu chuẩn, chỉ có thể được sử dụng bởi các máy khách MCP cục bộ
sse: Truyền tải Sự kiện do Máy chủ Gửi, hoàn hảo cho các máy khách từ xa
streamable-http: Truyền tải HTTP có thể Truyền phát, hoàn hảo cho các máy khách từ xa, mới hơn SSE

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

Khi truyền tải SSE được sử dụng, 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ể 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

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_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

[!MẸO] 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 container Docker.

Cài đặt qua Smithery

Để cài đặt Máy chủ Qdrant MCP 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" trong tệp 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 bộ sưu tập 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 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 tương thích MCP nào. Ví dụ: bạn có thể sử dụng nó với Cursor và VS Code, những công cụ cung cấp hỗ trợ tích hợp cho Giao thức Ngữ cảnh Mô hình.

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, sau đó 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 sử dụng giao thức truyền tải SSE. Mô tả về cách thêm máy chủ MCP vào Cursor có thể được tìm thấy trong https://docs.cursor.com/context/model-context-protocol#adding-an-mcp-server-to-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

[!MẸO] Chúng tôi đề xuất truyền tải SSE là 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 đó 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ữ đ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 các nhà phát triển tìm các triển khai hoặc mẫu sử dụng cụ thể

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

[!LƯU Ý] Các mô tả công cụ được cung cấp ở trên 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 thành công mcp-server-qdrant, 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 tác nhân tạo ra 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 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

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. Những mô tả được cung cấp ở trên 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ã với 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 Cài đặt Người dùng (JSON) của bạn trong VS Code. Bạn có thể thực hiện việc này bằng cách nhấn Ctrl + Shift + P và 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 bạn thích sử dụng Docker, hãy thêm cấu hình này thay thế:

{
  "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 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 không gian làm việc với Docker, hãy sử dụng điều 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 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á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 Giấy phép Apache 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 Giấy phép Apache 2.0. Để biết thêm chi tiết, vui lòng xem tệp LICENSE trong kho lưu trữ dự án.