allfunc/mcp-qdrant

MCP Qdrant服务器

一个强大的模型上下文协议（MCP）服务器，提供与Qdrant向量数据库的无缝集成。该服务器使AI应用能够执行高级向量操作、语义搜索和智能文档检索，并通过Ollama实现自动嵌入生成。

📋 目录

• 🚀 核心功能
• 🛠️ 可用工具
• 💾 安装与使用
• 🎯 高级负载过滤
• 🚀 快速启动示例
• 📚 资源

🚀 核心功能

向量数据库操作

• 集合管理：创建、配置和管理Qdrant集合，支持自定义向量维度和距离度量
• 智能点操作：插入、更新和删除带有丰富元数据支持的向量点
• 批处理：高效的批量操作，用于处理大型数据集

智能搜索能力

• 语义相似性搜索：使用余弦、欧几里得或点积距离度量查找相似向量
• 文本到向量搜索：一步完成自动文本嵌入生成和相似性搜索
• 高级过滤：强大的基于负载的过滤，支持复杂布尔逻辑
• 相关性评分：可配置的相似性阈值，用于精确控制

性能与可扩展性

• 负载索引：创建和管理索引以加快过滤操作
• 分页支持：高效滚动浏览大型结果集
• 连接池：优化与Qdrant和Ollama服务的连接
• 健康监控：内置健康检查和状态监控

开发者体验

• 自动嵌入：使用Ollama模型无缝进行文本到向量转换
• 灵活配置：基于环境的设置，带有合理的默认值
• 丰富元数据：存储和查询复杂JSON负载以及向量
• 错误处理：全面的错误报告和调试支持

🛠️ 可用工具

🔌 连接与健康

📚 集合管理

📝 点操作

🔍 搜索与发现

📖 数据导航

⚡ 性能与实用工具

🎯 高级负载过滤

MCP Qdrant服务器在搜索和滚动操作（qdrant_search_similar、qdrant_search_similar_text、qdrant_scroll和qdrant_scroll_all）中支持复杂的负载过滤。这允许基于元数据条件精确控制结果集。

过滤类型

🔹 简单过滤器

适用于基本键值匹配：

json
{
  "simpleFilter": {
    "category": "technology",
    "status": "published",
    "priority": 1
  }
}

🔹 复杂过滤器

用于高级布尔逻辑和范围查询：

基本匹配

json
{
  "filter": {
    "must": [
      { "key": "category", "match": { "value": "technology" } }
    ]
  }
}

多个必要条件

json
{
  "filter": {
    "must": [
      { "key": "category", "match": { "value": "technology" } },
      { "key": "status", "match": { "value": "active" } },
      { "key": "rating", "range": { "gte": 4.0 } }
    ]
  }
}

可选条件（OR逻辑）

json
{
  "filter": {
    "should": [
      { "key": "author", "match": { "value": "john_doe" } },
      { "key": "author", "match": { "value": "jane_smith" } },
      { "key": "featured", "match": { "value": true } }
    ]
  }
}

排除逻辑

json
{
  "filter": {
    "must": [
      { "key": "category", "match": { "value": "technology" } }
    ],
    "must_not": [
      { "key": "status", "match": { "value": "archived" } },
      { "key": "deprecated", "match": { "value": true } }
    ]
  }
}

范围过滤器

json
{
  "filter": {
    "must": [
      { "key": "score", "range": { "gte": 0.8, "lte": 1.0 } },
      { "key": "created_date", "range": { "gte": "2024-01-01" } },
      { "key": "views", "range": { "gt": 1000 } }
    ]
  }
}

复杂组合逻辑

json
{
  "filter": {
    "must": [
      { "key": "category", "match": { "value": "technology" } }
    ],
    "should": [
      { 
        "must": [
          { "key": "author", "match": { "value": "expert_author" } },
          { "key": "verified", "match": { "value": true } }
        ]
      },
      { "key": "trending", "match": { "value": true } }
    ],
    "must_not": [
      { "key": "status", "match": { "value": "archived" } }
    ]
  }
}

💾 安装与使用

选项1：使用Docker（推荐）

使用Docker是使用此MCP服务器的最简单方法：

bash
# 将MCP服务器以Stdio模式添加到VS Code
code --add-mcp '{"name":"mcp-qdrant","command":"docker","args":["run", "-i", "--rm", "--env-file", "'${HOME}'/.mcp-credentials", "--name", "mcp-qdrant", "--network", "host", "allfunc/mcp-qdrant", "stdio"]}'

bash
# 将MCP服务器以httpStream模式添加到VS Code
code --add-mcp '{"name":"mcp-qdrant","command":"docker","args":["run", "-i", "--rm", "--env-file", "'${HOME}'/.mcp-credentials", "--name", "mcp-qdrant", "--network", "host", "allfunc/mcp-qdrant"]}'

bash
# 将MCP服务器添加到Claude作为传输
# claude mcp add --transport http <名称> <URL>

claude mcp add -s user --transport http mcp-qdrant http://localhost/mcp

选项2：本地开发

bash
# 克隆并安装
git clone https://github.com/allfunc/mcp-qdrant.git
cd mcp-qdrant/app
bun install

# 运行服务器
bun run src/index.ts

选项3：使用Docker Run

bash
  docker run --rm -it \
    -p 65534:65534 \
    -p 65533:65533 \
    --env-file $HOME/.mcp-credentials \
    --network host \
    allfunc/mcp-qdrant 

环境配置

在主目录中创建.mcp-credentials文件，包含以下环境变量：

bash
# Qdrant配置
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your_api_key_here  # 可选

# 用于嵌入的Ollama配置
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=mxbai-embed-large

配置选项

🚀 快速启动示例

1. 连接到Qdrant：

   typescript
   // 服务器将使用您的环境配置自动连接
   

2. 创建集合：

   typescript
   qdrant_create_collection({
     name: "my_documents",
     vectorSize: 1024,
     distance: "Cosine"
   })
   

3. 插入带有自动嵌入的文本：

   typescript
   qdrant_insert_text({
     collectionName: "my_documents",
     text: "这是一篇关于机器学习的示例文档",
     payload: {
       category: "technology",
       author: "john_doe",
       timestamp: "2024-01-01"
     }
   })
   

4. 搜索相似内容：

   typescript
   qdrant_search_similar_text({
     collectionName: "my_documents",
     queryText: "人工智能",
     limit: 5,
     simpleFilter: {
       category: "technology"
     }
   })
   

📚 资源

• GitHub仓库：https://github.com/allfunc/mcp-qdrant
• Docker Hub：https://hub.docker.com/r/allfunc/mcp-qdrant
• Qdrant文档：[***]
• 模型上下文协议：https://modelcontextprotocol.io/