qdrant-mcp-server 0.1.0

A Model Context Protocol (MCP) server for Qdrant vector database with semantic search capabilities

Qdrant MCP Server

一个基于 Qdrant 向量数据库的 Model Context Protocol (MCP) 服务器，提供强大的语义搜索和知识管理功能。

✨ 特性

• 🚀 即插即用: 使用 uvx 一键运行，无需复杂配置
• 🔍 语义搜索: 基于向量相似度的智能搜索
• 🧠 多种嵌入模型: 支持本地 Sentence-Transformers 和在线 Jina AI
• 📝 完整 CRUD: 创建、读取、更新、删除知识条目
• 🔧 灵活配置: 通过环境变量自定义各项参数
• 🌐 标准协议: 完全符合 MCP 规范

📦 安装

使用 uvx (推荐)

最简单的方式是使用 uvx 直接运行:

uvx qdrant-mcp-server

使用 uv

uv pip install qdrant-mcp-server

使用 pip

pip install qdrant-mcp-server

🚀 快速开始

1. 配置环境变量

创建 .env 文件或设置环境变量:

# Qdrant 连接配置
QDRANT_URL=https://your-qdrant-instance.com:443
QDRANT_API_KEY=your-api-key-here
COLLECTION_NAME=my_knowledge_base

# 嵌入模型配置 (二选一)
# 选项1: 使用本地模型 (默认)
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
VECTOR_NAME=fast-all-minilm-l6-v2

# 选项2: 使用 Jina AI 在线模型
# EMBEDDING_MODEL=jina-embeddings-v3
# JINA_TOKEN=your-jina-api-key
# VECTOR_NAME=jina-embeddings-v3

2. 在 MCP 客户端中配置

Claude Desktop 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "qdrant": {
      "command": "uvx",
      "args": ["qdrant-mcp-server"],
      "env": {
        "QDRANT_URL": "https://your-instance.com:443",
        "QDRANT_API_KEY": "your-api-key",
        "COLLECTION_NAME": "knowledge_base"
      }
    }
  }
}

Roo Code / OpenCode 配置

编辑配置文件 (如 ~/.config/opencode/opencode.json):

{
  "mcp": {
    "qdrant": {
      "type": "local",
      "command": ["uvx", "qdrant-mcp-server"],
      "environment": {
        "QDRANT_URL": "https://your-instance.com:443",
        "QDRANT_API_KEY": "your-api-key",
        "COLLECTION_NAME": "knowledge_base"
      }
    }
  }
}

🛠️ 可用工具

qdrant-record

将文档存储到 Qdrant 向量数据库。

# 参数
{
  "document": "要存储的文档内容",  # 必需
  "metadata": {                    # 可选
    "source": "example.pdf",
    "author": "John Doe",
    "date": "2024-01-01"
  },
  "point_id": "custom-id-123"      # 可选，不提供则自动生成
}

qdrant-search

基于语义相似度搜索知识。

# 参数
{
  "query": "搜索关键词",           # 必需
  "limit": 5,                     # 可选，默认 5
  "score_threshold": 0.7,         # 可选，默认 0.0
  "filter_conditions": {          # 可选
    "must": [
      {
        "key": "metadata.source",
        "match": {"value": "example.pdf"}
      }
    ]
  }
}

qdrant-update

更新已存储的知识条目。

# 参数
{
  "point_id": "existing-id",      # 必需
  "document": "新的文档内容",      # 可选
  "metadata": {                   # 可选
    "updated": "2024-01-02"
  }
}

qdrant-delete

删除知识条目。

# 按 ID 删除
{
  "point_ids": "single-id"        # 或 ["id1", "id2"]
}

# 按条件删除
{
  "filter_conditions": {
    "must": [
      {
        "key": "metadata.source",
        "match": {"value": "old-doc.pdf"}
      }
    ]
  }
}

🔧 配置选项

环境变量	默认值	说明
QDRANT_URL	http://localhost:6333	Qdrant 服务器地址
QDRANT_API_KEY	-	Qdrant API 密钥 (云服务需要)
COLLECTION_NAME	default_collection	集合名称
EMBEDDING_MODEL	sentence-transformers/all-MiniLM-L6-v2	嵌入模型
VECTOR_NAME	自动检测	向量字段名称
JINA_TOKEN	-	Jina AI API 密钥 (使用 Jina 时需要)

🌟 使用示例

1. 存储知识

请将这段内容存储到知识库：
"人工智能是计算机科学的一个分支，致力于创建能够执行通常需要人类智能的任务的系统。"

2. 搜索知识

在知识库中搜索关于"机器学习"的内容

3. 更新知识

更新 ID 为 "doc-123" 的文档，添加元数据 {"verified": true}

🏗️ 开发

从源码安装

git clone https://github.com/fiyen/qdrant-mcp-server.git
cd qdrant-mcp-server
uv pip install -e ".[dev]"

运行测试

pytest

代码格式化

black src/
ruff check src/

📚 文档

• MCP 协议文档
• Qdrant 文档
• Sentence Transformers
• Jina AI Embeddings

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

• Qdrant - 高性能向量数据库
• Anthropic - MCP 协议
• Sentence Transformers - 嵌入模型
• Jina AI - 在线嵌入服务

📧 联系

• 作者: fiyen
• Email: [e-mail]
• GitHub: @fiyen

---

⭐ 如果这个项目对您有帮助，请给个 Star！