Qdrant Gemini MCP

Qdrant Gemini MCP服务器

MCP（模型上下文协议）服务器，用于使用Gemini嵌入搜索Qdrant中索引的文档。非常适合将技术文档搜索集成到AI助手中。

特性

• 🔍 语义搜索：使用Gemini强大的嵌入功能搜索索引文档
• 📚 多格式支持：索引PDF、Word（.docx）、Markdown、HTML和TXT文档
• 🚀 MCP集成：通过模型上下文协议公开搜索功能
• 🔄 增量索引：跳过已处理文档的智能索引
• 🎯 技术文档：针对技术文档进行了优化（适用于任何文档）
• 🏠 本地处理：文档文本提取在本地进行（只有嵌入需要互联网）

建筑

该项目由三个主要部分组成：

1. 索引文档 (index_pdfs.py)：从多种文档格式中提取文本，生成嵌入，并将其存储在Qdrant中
2. 搜索 (search_qdrant.py)：用于搜索索引文档的CLI工具
3. MCP服务器 (server.py)：通过MCP为AI助手提供搜索和索引功能

支持的文档格式

• PDF （.pdf）-可移植文档格式
• 字 （.docx）-微软Word文档
• 标记语言 （.md，.markdown）-markdown文件
• 超文本标记语言 （.html、.htm）-网页
• 文本 （.txt）-纯文本文件

先决条件

• Python 3.10或更高版本
• Qdrant实例（本地或云）
• Gemini API密钥

安装

1.克隆存储库

git clone https://github.com/EugenioSerrano/qdrant-gemini-mcp.git
cd qdrant-gemini-mcp

2.创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3.安装依赖项

pip install -e .

使用测试工具进行开发：

pip install -e ".[dev]"

4.配置环境变量

复制示例环境文件并对其进行编辑：

cp .env.example .env

编辑 .env 并添加您的Gemini API密钥：

GEMINI_API_KEY=your_actual_api_key_here
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=proyecto-stm32

从以下位置获取Gemini API密钥：https://makersuite.google.com/app/apikey

5.启动Qdrant（如果在本地运行）

使用Docker：

docker run -p 6333:6333 qdrant/qdrant

用法

索引文档

索引目录中所有支持的文档（PDF、Word、Markdown、HTML、TXT）：

qdrant-gemini-index /path/to/documents/directory

强制重新索引（如果要更新现有文档，则很有用）：

qdrant-gemini-index /path/to/documents/directory --force

索引器将自动检测并处理目录中所有支持的文件格式。

从CLI搜索

qdrant-gemini-search "your search query here"

例子：

qdrant-gemini-search "STM32 clock configuration"

作为MCP服务器运行

MCP服务器可以在您的MCP客户端中配置（如Claude Desktop或VS Code）：

{
  "mcpServers": {
    "qdrant-gemini": {
      "command": "python",
      "args": [
        "/home/eugenio/GitHubRepos/qdrant-gemini-mcp/src/qdrant_gemini_mcp/server.py"
      ],
      "env": {
        "GEMINI_API_KEY": "your_api_key",
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_COLLECTION": "proyecto-stm32"
      }
    }
  }
}

或者使用已安装的脚本：

qdrant-gemini-server

VS代码MCP配置

添加到您的 ~/.config/Code/User/mcp.json:

{
  "servers": {
    "qdrant-gemini": {
      "command": "python",
      "args": [
        "-m",
        "qdrant_gemini_mcp.server"
      ],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here",
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_COLLECTION": "proyecto-stm32"
      },
      "type": "stdio"
    }
  }
}

MCP工具

服务器公开以下MCP工具：

search-stm32-docs

使用语义搜索在索引文档中搜索。

参数：

• query （字符串，必填）：搜索查询
• limit （整数，可选）：最大结果数（默认值：5）

退货：

• 相关文档块列表，包括：

- 得分（相关性） - 文件名 - 块索引 - 文本内容

发展

项目结构

qdrant-gemini-mcp/
├── src/
│   └── qdrant_gemini_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server
│       ├── index_pdfs.py      # PDF indexing
│       └── search_qdrant.py   # Search CLI
├── tests/
│   └── test_server.py
├── .env                        # Your environment variables (not in git)
├── .env.example               # Template for environment variables
├── pyproject.toml             # Project configuration
├── requirements.txt           # Dependencies
└── README.md

运行测试

pytest

覆盖范围：

pytest --cov=qdrant_gemini_mcp

运作原理

1. 索引阶段:

- 阅读PDF并提取文本 - 文本被分割成重叠的块（1000个字符，200个重叠） - 每个块都使用Gemini嵌入 text-embedding-004 模型 - 嵌入内容与元数据（文件名、块索引、文本）一起存储在Qdrant中

1. 搜索阶段:

- 使用相同的Gemini模型嵌入查询 - Qdrant执行余弦相似性搜索 - 返回前K个最相关的块

1. MCP集成:

- 服务器通过模型上下文协议公开搜索功能 - AI助手可以调用搜索工具 - 结果的格式便于使用

配置

环境变量

• GEMINI_API_KEY：您的Google Gemini API密钥（必需）
• QDRANT_URL：Qdrant服务器URL（默认值： http://localhost:6333)
• QDRANT_COLLECTION：Qdrant中的集合名称（默认值： proyecto-stm32)

嵌入模型

该项目使用Gemini的 text-embedding-004 生成768维嵌入的模型。

分块策略

• 块大小：1000个字符
• 重叠：200个字符
• 这可确保跨块边界保留上下文

故障排除

“GEMINI_API_KEY未配置”

确保您已创建 .env 使用API密钥文件：

cp .env.example .env
# Edit .env and add your key

“集合为空”

先索引一些PDF：

qdrant-gemini-index /path/to/pdfs/

Qdrant连接错误

确保Qdrant正在运行：

docker ps | grep qdrant

如果没有运行，请启动它：

docker run -p 6333:6333 qdrant/qdrant

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请随时提交拉取请求。

致谢

• 内置于 模型上下文协议
• 用途 谷歌双子座 用于嵌入
• 由...驱动 Qdrant 矢量数据库