qdrant-mcp-server 0.1.0
A Model Context Protocol (MCP) server for Qdrant vector database with semantic search capabilities
Requires Python: >=3.10
Keywords: mcp, qdrant, vector-database, semantic-search, embeddings, ai

# Qdrant MCP Server

[![PyPI version](https://badge.fury.io/py/qdrant-mcp-server.svg)](https://badge.fury.io/py/qdrant-mcp-server)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个基于 [Qdrant](https://qdrant.tech/) 向量数据库的 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，提供强大的语义搜索和知识管理功能。

## ✨ 特性

- 🚀 **即插即用**: 使用 `uvx` 一键运行，无需复杂配置
- 🔍 **语义搜索**: 基于向量相似度的智能搜索
- 🧠 **多种嵌入模型**: 支持本地 Sentence-Transformers 和在线 Jina AI
- 📝 **完整 CRUD**: 创建、读取、更新、删除知识条目
- 🔧 **灵活配置**: 通过环境变量自定义各项参数
- 🌐 **标准协议**: 完全符合 MCP 规范

## 📦 安装

### 使用 uvx (推荐)

最简单的方式是使用 `uvx` 直接运行:

```bash
uvx qdrant-mcp-server
```

### 使用 uv

```bash
uv pip install qdrant-mcp-server
```

### 使用 pip

```bash
pip install qdrant-mcp-server
```

## 🚀 快速开始

### 1. 配置环境变量

创建 `.env` 文件或设置环境变量:

```bash
# 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`:

```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`):

```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 向量数据库。

```python
# 参数
{
  "document": "要存储的文档内容",  # 必需
  "metadata": {                    # 可选
    "source": "example.pdf",
    "author": "John Doe",
    "date": "2024-01-01"
  },
  "point_id": "custom-id-123"      # 可选，不提供则自动生成
}
```

### qdrant-search

基于语义相似度搜索知识。

```python
# 参数
{
  "query": "搜索关键词",           # 必需
  "limit": 5,                     # 可选，默认 5
  "score_threshold": 0.7,         # 可选，默认 0.0
  "filter_conditions": {          # 可选
    "must": [
      {
        "key": "metadata.source",
        "match": {"value": "example.pdf"}
      }
    ]
  }
}
```

### qdrant-update

更新已存储的知识条目。

```python
# 参数
{
  "point_id": "existing-id",      # 必需
  "document": "新的文档内容",      # 可选
  "metadata": {                   # 可选
    "updated": "2024-01-02"
  }
}
```

### qdrant-delete

删除知识条目。

```python
# 按 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}
```

## 🏗️ 开发

### 从源码安装

```bash
git clone https://github.com/fiyen/qdrant-mcp-server.git
cd qdrant-mcp-server
uv pip install -e ".[dev]"
```

### 运行测试

```bash
pytest
```

### 代码格式化

```bash
black src/
ruff check src/
```

## 📚 文档

- [MCP 协议文档](https://modelcontextprotocol.io/)
- [Qdrant 文档](https://qdrant.tech/documentation/)
- [Sentence Transformers](https://www.sbert.net/)
- [Jina AI Embeddings](https://jina.ai/embeddings/)

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

- [Qdrant](https://qdrant.tech/) - 高性能向量数据库
- [Anthropic](https://www.anthropic.com/) - MCP 协议
- [Sentence Transformers](https://www.sbert.net/) - 嵌入模型
- [Jina AI](https://jina.ai/) - 在线嵌入服务

## 📧 联系

- 作者: fiyen
- Email: 623320480@qq.com
- GitHub: [@fiyen](https://github.com/fiyen)

---

⭐ 如果这个项目对您有帮助，请给个 Star！