使用说明

Qdrant MCP Server

A self-contained RAG toolkit for AI assistants — vector database, document ingestion, and semantic search in one package

Tools • Quickstart • Embedding Providers • Client Configuration • Configuration • Docker • Troubleshooting

Qdrant MCP Server使AI助手能够使用内置的 Qdrant 矢量数据库。它实现了模型上下文协议（MCP），这意味着任何兼容MCP的客户端——Claude Desktop、Claude Code、Claude.ai或第三方工具——都可以通过自然对话将其用作知识库。

它是如何工作的： 您摄取文档（PDF、文本文件或原始文本）。服务器将它们分块，通过您选择的提供者生成嵌入，并将向量存储在Qdrant中。当你问一个问题时，它会嵌入你的查询，并返回最相关的段落，包括来源归因和相似性得分。

内容包括：

Qdrant矢量数据库 --捆绑在Docker中，自动启动 docker compose up无需单独安装。（如果你有Qdrant实例，也可以指向它。）
6个MCP工具 --搜索、摄取文本、摄取文件（PDF/text/markdown/HTML）、列出集合、集合详细信息和删除——所有这些都可以通过对话访问
与提供者无关的嵌入 -与任何与OpenAI兼容的API配合使用：本地（Ollama，llama.cpp）或云（OpenAI，Anthropic/Vyage，Google，Azure）。通过更改一个URL来切换提供商。
双重运输 --用于Claude Desktop和Claude Code的stdio，用于Claude.ai的流式HTTP或任何支持HTTP的MCP客户端
跨平台 --通过原生Python或Docker在Linux、macOS和Windows上运行

内置于 FastMCP python

用法示例

服务器运行并连接到MCP客户端后，通过自然对话进行交互：

搜索文档

你：在我的文档中搜索合同终止条款

Search results for: contract termination clauses

Collection: documents | Results: 3

[1] 0.8234 — services-agreement.pdf p.12 (chunk 23)
Either party may terminate this Agreement upon thirty (30) days written
notice to the other party. In the event of a material breach...

[2] 0.7891 — employee-handbook.pdf p.45 (chunk 67)
Employment may be terminated at will by either party with or without
cause, subject to the notice requirements in Section 8.2...

摄入文件

你：摄取此PDF:/home/user/Documents/quarterly-report.PDF

{
  "status": "ok",
  "file": "/home/user/Documents/quarterly-report.pdf",
  "collection": "documents",
  "pages_extracted": 24,
  "chunks_created": 47,
  "points_upserted": 47,
  "text_length": 38291
}

摄取原始文本

你：将此文本记为“会议笔记-25年3月”：我们讨论了第一季度的路线图，并同意优先考虑API的重新设计。预算已批准增加两名员工。..

{
  "status": "ok",
  "source": "meeting-notes-mar-25",
  "collection": "documents",
  "chunks_created": 1,
  "points_upserted": 1,
  "text_length": 142
}

浏览收藏

你：我有什么收藏？

Qdrant Collections (2 total)

| Collection | Points | Dimension | Distance |
|------------|--------|-----------|----------|
| documents  | 198    | 768       | Cosine   |
| research   | 43     | 768       | Cosine   |

删除文档

你：从源“旧报告.pdf”中删除所有块

服务器需要明确确认破坏性操作——LLM必须通过 confirm=true:

{
  "status": "ok",
  "collection": "documents",
  "points_before": 198,
  "points_after": 185,
  "points_deleted": 13,
  "filter_source": "/home/user/Documents/old-report.pdf"
}

使用文档

在哪里放置文件

文件必须位于中列出的目录中 ALLOWED_INGEST_PATHS （配置于 config.py).默认情况下，此设置为您的主目录-- 根据您的环境缩小范围:

# config.py — Linux / macOS
ALLOWED_INGEST_PATHS = [
    "/home/youruser/Documents/",
    "/home/youruser/projects/",
    "/data/shared/",
]

# config.py — Windows
ALLOWED_INGEST_PATHS = [
    "C:\\Users\\youruser\\Documents\\",
    "C:\\Users\\youruser\\projects\\",
    "D:\\shared\\",
]

这些目录之外的任何路径都将被拒绝，并出现错误。这是一种防止意外文件访问的安全措施。路径验证使用 os.path.abspath()，因此正斜杠和反斜杠都适用于Windows。

支持的文件格式

格式	扩展名	注释
PDF	`.pdf`	通过pymupdf提取的文本；元数据中保留的页面边界
纯文本	`.txt`	直接摄入
Markdown	`.md`	以纯文本形式摄入（标记以块形式保留）
CSV	`.csv`	作为原始文本摄入——行成为块的一部分
JSON	`.json`	作为原始文本摄入
HTML	`.html`, `.htm`	摄入原始HTML（包括标签）；清洁结果的预处理
日志文件	`.log`	直接摄入
重新结构化文本	`.rst`	以纯文本形式摄入

尝试以纯文本形式保存扩展名无法识别的文件。

不支持： Word文档(.docx)，Excel(.xlsx)，图像、音频或无OCR文本层的扫描PDF。在摄入之前将其转换为PDF或文本。

更好检索的提示

摄入前：

清理您的PDF。 扫描的文档需要一个OCR文本层——通过尝试在PDF查看器中选择文本来检查。如果您无法选择文本，PDF将仅包含图像，并将提取为空。
移除样板。 每页中的页眉、页脚、页码和法律免责声明都会产生噪音。如果你能预先处理它们，你的搜索质量就会提高。
按主题拆分大型文档。 将500页的手册合并为一个文件是可行的，但如果将其拆分为逻辑部分（每章或每个主题一个文件），搜索会更精确。
使用描述性源名称。 这 source 参数可通过以下方式搜索 source_filter.名称如下 q1-2026-financial-review 比 doc1.pdf.

调整块设置：

默认块大小（512字） 适用于大多数文档。较大的块（1000+）保留了更多的上下文，但降低了精度。较小的块（200）更精确，但可能会失去上下文。
重叠（64字） 确保跨越块边界的概念不会丢失。对于包含长多句概念的技术文档，增加到100-128。
重新摄入源 具有相同名称的块会覆盖之前的块（确定性ID）。更新文档后，您可以安全地重新摄取。

整理藏品：

使用默认值 documents 一般用途收藏
为不同域创建单独的集合： qdrant_ingest_file 接受a collection 参数
例子： legal 对于合同， technical 对于规格， research 对于论文，然后在特定集合中搜索重点结果

工具

工具	描述	只读	破坏性	幂等
`qdrant_search`	带分数阈值和源过滤的语义搜索	是	否	是
`qdrant_ingest_text`	分块、嵌入和存储原始文本	no	no	no
`qdrant_ingest_file`	从PDF/文本文件中提取文本，然后摄取	no	no	no
`qdrant_list_collections`	列出所有具有点计数和向量配置的集合	yes	no	yes
`qdrant_collection_info`	特定收藏的详细统计数据	是	否	是
`qdrant_delete`	按ID或源筛选器删除点（需要 `confirm=true`)	没有	是	是的

所有工具均支持 标记语言 和 JSON 通过响应格式 response_format 参数。工具注释遵循 MCP规范并告知客户工具行为，以便做出许可和安全决策。

建筑

┌──────────────────────────────────────────────────┐
│                   MCP Clients                     │
│  Claude Code (stdio)  │  Claude.ai / OpenClaw     │
│                       │  (streamable HTTP :8090)  │
└──────────┬────────────┴──────────┬────────────────┘
           │                       │
           ▼                       ▼
┌──────────────────────────────────────────────────┐
│              qdrant_mcp (FastMCP)                  │
│                                                    │
│  embeddings.py ──→ Any OpenAI-compatible API       │
│  tools/        ──→ Qdrant client                   │
│  rag/lib/      ──→ Chunker, PDF extractor          │
└──────────┬───────────────────────┬────────────────┘
           │                       │
           ▼                       ▼
   Embedding Provider          Qdrant :6333
   (Ollama, OpenAI,           (vector store)
    llama.cpp, etc.)

先决条件

必需

Python 3.10+ （在3.10和3.11上测试）-- 或 码头工人 （它捆绑了所有东西）
Qdrant --捆绑在 docker compose up，或单独安装对于原生Python
嵌入提供者 --任何兼容OpenAI的 /v1/embeddings 端点（请参见嵌入提供商)

系统要求

资源	最小	推荐	备注
随机存取存储器	512 MB	1 GB+	MCP服务器使用约50 MB。Qdrant根据集合大小使用100-500MB。本地嵌入模型增加了500 MB–4 GB。
磁盘	500 MB	1 GB+	项目+Python依赖项（约200 MB），Qdrant数据（因摄入的文档而异），pymupdf（约25 MB）。
图形处理器	无	可选	仅适用于本地GPU加速嵌入（Ollama）。云提供商（OpenAI、Voyage）不需要GPU。通过llama.cpp嵌入CPU无需GPU即可工作。
操作系统	Linux、macOS、Windows	Linux	原生Python和Docker支持的所有平台。
码头工人	不需要	可选	`docker compose up` 启动Qdrant和MCP服务器。原生Python可以在没有Docker的情况下工作（需要单独安装Qdrant）。
网络	localhost	LAN	Qdrant和嵌入提供程序必须可访问。HTTP传输在配置的绑定地址上公开端口8090。

缩放说明： RAM和磁盘随着摄入的数据量而增长。每个768维矢量（nomic嵌入文本）在Qdrant中使用约3 KB。10000个文档块≈30 MB的矢量数据加上有效载荷文本存储。对于大多数个人/团队使用，这是可以忽略不计的。

快速启动

1.克隆并安装

Linux/macOS：

git clone https://github.com/ncasfl/Qdrant-MCP.git
cd Qdrant-MCP

# Create and activate a virtual environment (recommended)
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install pymupdf  # for PDF support

Ubuntu/Debian注意事项： 如果 python3 -m venv 出现“ensureepip不可用”失败，请先安装venv包： sudo apt install python3.10-venv （调整版本以匹配您的Python）。

Windows（PowerShell）：

git clone https://github.com/ncasfl/Qdrant-MCP.git
cd Qdrant-MCP

# Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt
pip install pymupdf

Windows注意事项： 使用 python （不是 python3)--Windows Python安装程序注册为 python。如果你遇到“无法识别”的错误，请确保Python在你的系统PATH中。

为什么是虚拟环境？ 服务器依赖于 mcp, qdrant-client, pydantic，以及它们的传递依赖关系。venv将这些与Python系统隔离开来。Claude Code MCP配置和Docker镜像都会自动处理这个问题——venv只需要用于本机/手动安装。

2.配置您的嵌入提供程序

编辑 qdrant_mcp/config.py 或设置环境变量：

Linux/macOS（bash）：

export EMBED_BASE_URL=http://localhost:11434/v1
export EMBED_MODEL=nomic-embed-text

# For cloud providers:
export EMBED_BASE_URL=https://api.openai.com/v1
export EMBED_MODEL=text-embedding-3-small
export EMBED_API_KEY=sk-...

Windows（PowerShell）：

$env:EMBED_BASE_URL = "http://localhost:11434/v1"
$env:EMBED_MODEL = "nomic-embed-text"

# For cloud providers:
$env:EMBED_BASE_URL = "https://api.openai.com/v1"
$env:EMBED_MODEL = "text-embedding-3-small"
$env:EMBED_API_KEY = "sk-..."

3.运行服务器

Linux/macOS：

# stdio (for Claude Code / Claude Desktop):
PYTHONPATH="$(pwd)" python3 -m qdrant_mcp --transport stdio

# HTTP (for Claude.ai or other HTTP clients):
PYTHONPATH="$(pwd)" python3 -m qdrant_mcp --transport streamable-http --port 8090

Windows（PowerShell）：

# stdio:
$env:PYTHONPATH = (Get-Location).Path
python -m qdrant_mcp --transport stdio

# HTTP:
$env:PYTHONPATH = (Get-Location).Path
python -m qdrant_mcp --transport streamable-http --port 8090

4.连接客户端

看客户端配置在......下面

嵌入提供商

服务器使用OpenAI兼容 /v1/embeddings API格式。这适用于各种开箱即用的提供商。

本地供应商

Ollama (local GPU/CPU)

EMBED_BASE_URL=http://localhost:11434/v1
EMBED_MODEL=nomic-embed-text
# No API key needed

安装Ollama并拉取模型：

ollama pull nomic-embed-text

llama-server / llama.cpp (local CPU/GPU)

EMBED_BASE_URL=http://localhost:8080/v1
EMBED_MODEL=your-model-name
# No API key needed

使用嵌入模型启动llama服务器：

llama-server -m your-embedding-model.gguf --embedding --port 8080

云提供商

OpenAI

EMBED_BASE_URL=https://api.openai.com/v1
EMBED_MODEL=text-embedding-3-small
EMBED_API_KEY=sk-...
EMBED_QUERY_PREFIX=
EMBED_DOCUMENT_PREFIX=

模型： text-embedding-3-small （1536昏暗）， text-embedding-3-large （3072昏暗）

Anthropic (Claude) via Voyage AI

Anthropic推荐 Voyage AI 对于嵌入：

EMBED_BASE_URL=https://api.voyageai.com/v1
EMBED_MODEL=voyage-3
EMBED_API_KEY=pa-...
EMBED_QUERY_PREFIX=
EMBED_DOCUMENT_PREFIX=

模型： voyage-3 （1024暗）， voyage-3-lite （512暗）， voyage-code-3 （代码优化）

Google Gemini (via OpenAI-compatible proxy)

使用轻量级LLM 作为公开Gemini以OpenAI格式嵌入API的代理：

# Start LiteLLM proxy
litellm --model gemini/text-embedding-004 --port 4000

# Configure qdrant_mcp
EMBED_BASE_URL=http://localhost:4000/v1
EMBED_MODEL=gemini/text-embedding-004
EMBED_API_KEY=your-gemini-key
EMBED_QUERY_PREFIX=
EMBED_DOCUMENT_PREFIX=

Azure OpenAI

EMBED_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment
EMBED_MODEL=text-embedding-3-small
EMBED_API_KEY=your-azure-key
EMBED_QUERY_PREFIX=
EMBED_DOCUMENT_PREFIX=

非对称模型与对称模型： 模特们喜欢 nomic-embed-text 为查询使用不同的前缀(search_query: )和文件(search_document: )以提高检索质量。OpenAI、Voyage和大多数云模型都是对称的——将两个前缀都设置为空字符串。

客户端配置

克劳德桌面（stdio）

添加到您的Claude Desktop配置文件中：

平台	配置路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
窗户	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

macOS/Linux：

{
  "mcpServers": {
    "qdrant": {
      "command": "/path/to/Qdrant-MCP/.venv/bin/python3",
      "args": ["-m", "qdrant_mcp", "--transport", "stdio"],
      "env": {
        "PYTHONPATH": "/path/to/Qdrant-MCP"
      }
    }
  }
}

窗户：

{
  "mcpServers": {
    "qdrant": {
      "command": "C:\\path\\to\\Qdrant-MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "qdrant_mcp", "--transport", "stdio"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\Qdrant-MCP",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

重要提示： Claude Desktop需要 完全重新启动 （退出并重新打开，而不仅仅是关闭窗口）以获取配置更改。使用绝对路径——Claude Desktop不会继承您的shell PATH 或工作目录。在Windows上，添加 PYTHONIOENCODING: utf-8 以避免编码问题。

Debugging Claude Desktop connection

如果服务器未出现，请检查MCP日志：

平台	日志路径
macOS	`~/Library/Logs/Claude/mcp.log` 和 `mcp-server-qdrant.log`
窗户	`%APPDATA%\Claude\logs\`

常见问题：配置中的JSON语法错误（无声失败）、Python路径错误、缺失 PYTHONPATH.

克劳德代码/VS代码扩展（stdio）

添加到您的 ~/.mcp.json （或项目级别 .mcp.json):

Linux/macOS：

{
  "mcpServers": {
    "qdrant": {
      "command": "/path/to/Qdrant-MCP/.venv/bin/python3",
      "args": ["-m", "qdrant_mcp", "--transport", "stdio"],
      "cwd": "/path/to/Qdrant-MCP",
      "env": {
        "PYTHONPATH": "/path/to/Qdrant-MCP"
      }
    }
  }
}

窗户：

{
  "mcpServers": {
    "qdrant": {
      "command": "C:\\path\\to\\Qdrant-MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "qdrant_mcp", "--transport", "stdio"],
      "cwd": "C:\\path\\to\\Qdrant-MCP",
      "env": {
        "PYTHONPATH": "C:\\path\\to\\Qdrant-MCP"
      }
    }
  }
}

注：点 command 因此Claude Code使用隔离环境。如果你全局安装了依赖项或使用Docker， python3 （或 python 在Windows上）工作。

重新启动Claude Code以获取新服务器。

第.ai条（HTTP）

以HTTP模式启动服务器（请参阅快速启动或码头工人)
在Claude.ai设置中，添加远程MCP服务器： http://your-host:8090/mcp

OpenClaw/Claude代码分叉（通过mcp-remote实现HTTP）

对于仅支持stdio的MCP客户端，请使用 mcp遥控器作为一座桥梁：

{
  "mcpServers": {
    "qdrant": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:8090/mcp"]
    }
  }
}

任何兼容OpenAI的客户端

HTTP端点位于 /mcp 使用标准的MCP流式HTTP协议。任何兼容MCP的客户端都可以连接。

配置参考

所有设置都可以在中配置 qdrant_mcp/config.py 或者用环境变量覆盖。

嵌入

环境变量	默认值	描述
`EMBED_BASE_URL`	`http://localhost:11434/v1`	与OpenAI兼容的嵌入API基础URL
`EMBED_MODEL`	`nomic-embed-text`	嵌入模型名称
`EMBED_API_KEY`	（空）	云提供商的API密钥
`EMBED_QUERY_PREFIX`	`search_query:`	在搜索查询前添加前缀
`EMBED_DOCUMENT_PREFIX`	`search_document:`	文档块前缀

Qdrant

设置	默认值	说明
`QDRANT_HOST`	`localhost`	Qdrant服务器主机。Docker compose将其设置为 `qdrant` （容器名称）自动。覆盖 `QDRANT_HOST` 有人。
`QDRANT_PORT`	`6333`	Qdrant REST API端口。使用重写 `QDRANT_PORT` 有人。

服务器

设置	默认值	说明
`MCP_HTTP_PORT`	`8090`	HTTP传输端口
`MCP_HTTP_HOST`	`0.0.0.0`	HTTP绑定地址
`DEFAULT_COLLECTION`	`documents`	默认Qdrant收集
`DEFAULT_CHUNK_SIZE`	`512`	每块单词数
`DEFAULT_CHUNK_OVERLAP`	`64`	词块之间的重叠

安全

设置	默认值	说明
`ALLOWED_INGEST_PATHS`	（按部署配置）	目录白名单 `qdrant_ingest_file`

重要提示： 更新 ALLOWED_INGEST_PATHS 在 config.py 以适应您的环境。默认情况下，文件摄取仅限于特定目录。

码头工人

这 docker-compose.yaml 捆绑包 Qdrant和MCP服务器 --一个命令启动一切：

docker compose build
docker compose up -d

这将开始：

Qdrant （矢量数据库）位于6333端口，具有持久存储
qdrant mcp 端口8090上的（MCP服务器），预配置为连接到捆绑的Qdrant

验证：

# Qdrant health
curl -s http://localhost:6333/healthz

# MCP server
curl -s http://localhost:8090/mcp

数据持久化

Qdrant数据存储在一个命名的Docker卷中(qdrant_data).您的矢量和集合在以下方面持续存在：

容器重新启动(docker compose restart)
集装箱重建(docker compose build && docker compose up -d)
docker compose down （停止容器，保持体积）

只有明确删除卷才能销毁数据： docker volume rm qdrant-mcp_qdrant_data

在Docker中嵌入提供者

MCP服务器需要一个嵌入提供程序。默认情况下，compose文件通过以下方式指向主机上的Ollama host.docker.internal:

environment:
  - EMBED_BASE_URL=http://host.docker.internal:11434/v1

对于 云提供商 （无需本地Ollama），在编写文件中重写或 .env 文件：

environment:
  - EMBED_BASE_URL=https://api.openai.com/v1
  - EMBED_MODEL=text-embedding-3-small
  - EMBED_API_KEY=${OPENAI_API_KEY}

云提供商在所有平台上工作 （Linux、macOS、Windows），无需额外配置——嵌入调用通过互联网发出，而不是发送到本地主机。

平台说明

Linux

开箱即用。 host.docker.internal 通过解析到主机 extra_hosts compose文件中的指令。客人可以使用Ollama和其他主机服务。

macOS / Windows (Docker Desktop)

开箱即用。Docker桌面原生支持 host.docker.internalOllama及其他主机服务均可联系。

如果你不想使用Docker，原生Python方法在macOS和Windows上运行良好：

PYTHONPATH="$(pwd)" python3 -m qdrant_mcp --transport streamable-http --port 8090

注意：你仍然需要Qdrant单独运行（通过Docker或 Qdrant云).

使用现有的Qdrant实例

如果你已经运行了Qdrant，你可以跳过捆绑的。创建一个 docker-compose.override.yaml:

services:
  qdrant:
    # Replace bundled Qdrant with a no-op
    image: busybox
    command: ["true"]
    restart: "no"
    ports: !reset []
    volumes: !reset []
    deploy: !reset {}
  qdrant-mcp:
    environment:
      # Point at your existing Qdrant
      - QDRANT_HOST=your-qdrant-host
      - QDRANT_PORT=6333

提示： 添加 docker-compose.override.yaml 给你的 .gitignore --这是特定于部署的。

对于原生Python安装，设置 QDRANT_HOST 在您的环境中或编辑 config.py 直接。

Docker镜像详细信息

组件	图像	大小
Qdrant	`qdrant/qdrant:v1.13.6`	~100 MB
qdrant mcp	自定义(`python:3.11-slim` +deps）	~250 MB

两个容器都有资源限制（Qdrant:1 GB RAM，MCP:512 MB RAM）。

项目结构

Qdrant-MCP/
├── qdrant_mcp/
│   ├── __init__.py
│   ├── __main__.py          # Entry point: --transport stdio|streamable-http
│   ├── server.py            # FastMCP server, lifespan, logging setup
│   ├── config.py            # All configuration constants
│   ├── embeddings.py        # Provider-agnostic OpenAI-compatible embedding client
│   └── tools/
│       ├── search.py        # qdrant_search
│       ├── ingest.py        # qdrant_ingest_text, qdrant_ingest_file
│       ├── collections.py   # qdrant_list_collections, qdrant_collection_info
│       └── delete.py        # qdrant_delete
├── rag/
│   └── lib/
│       ├── chunker.py       # Text chunking with overlap + page tracking
│       ├── extract.py       # PDF/text extraction via pymupdf
│       └── store.py         # Qdrant CRUD + search operations
├── Dockerfile
├── docker-compose.yaml
├── requirements.txt
├── LICENSE
└── README.md

捆绑模块： `rag/lib/`

服务器包括用于文本分块的共享模块(chunker.py)，PDF提取(extract.py)，以及Qdrant存储操作(store.py).这些内容捆绑在存储库中 rag/lib/ 并且不需要额外的设置——它们包含在 PYTHONPATH 当您按照快速入门说明进行操作时，会自动执行。

日志记录

模式	目的地	备注
stdio	stderr	保持MCP协议的stdout干净
HTTP	日志文件（可配置）	默认值： `~/logs/qdrant-mcp.log`

日志格式： 2026-03-25 19:38:11 INFO qdrant_mcp.search Embedding query: ...

每个工具模块都有自己的记录器(qdrant_mcp.search, qdrant_mcp.ingest, qdrant_mcp.delete, qdrant_mcp.collections).

错误处理

所有工具都返回可操作的错误消息，而不是原始的回溯：

失败	消息
嵌入提供程序无法访问	“Ollama无法访问（嵌入失败）。它是否在端口11434上运行？”
Qdrant无法访问	“无法访问Qdrant”
未找到集合	“未找到集合'X'”
文件未找到	“文件未找到：/path/to/File”
白名单外的路径	“路径在允许的目录之外”
无效参数	特定范围/约束消息
PDF提取失败	“无法从/path提取文本--{details}”

故障排除

Server not found / ENOENT error

症状： spawn python3 ENOENT 或者服务器未出现在客户端中。

原因： MCP客户端找不到Python可执行文件。Claude Desktop和一些编辑器以最小的速度启动服务器 PATH 这不包括shell的自定义（pyenv、nvm、conda等）。

修复： 使用 绝对路径 在你的配置中使用venv Python：

# Find your venv Python path
which python3                              # system
/path/to/Qdrant-MCP/.venv/bin/python3     # venv (Linux/macOS)
/path/to/Qdrant-MCP/.venv/Scripts/python.exe  # venv (Windows)

ModuleNotFoundError: No module named 'qdrant_mcp'

原因： PYTHONPATH 未设置或指向错误的目录。

修复： 确保您的客户端配置包括 PYTHONPATH 指向项目根：

"env": {
  "PYTHONPATH": "/path/to/Qdrant-MCP"
}

如果你也使用 rag/lib/ 模块，包括父目录：

"env": {
  "PYTHONPATH": "/path/to/Qdrant-MCP:/path/to/parent-containing-rag"
}

ModuleNotFoundError: No module named 'mcp' (or qdrant_client, etc.)

原因： 这 command 在您的配置中指向系统Python，但依赖项安装在虚拟环境中。

修复： 点 command 转换为venv Python二进制文件，而不是 python3:

"command": "/path/to/Qdrant-MCP/.venv/bin/python3"

Embedding failed / Ollama not reachable

原因： 嵌入提供程序未运行或URL错误。

修复：

验证您的提供商是否正在运行： curl http://localhost:11434/v1/embeddings -d '{"model":"nomic-embed-text","input":["test"]}'
检查 EMBED_BASE_URL 匹配您的提供商的实际URL
对于云提供商，请验证 EMBED_API_KEY 已设置（检查env-var，而不仅仅是config.py）

Windows: npx not found for mcp-remote bridge

原因： 视窗 spawn 默认情况下不调用shell，以及 npx 是一个shell脚本。

修复： 使用 cmd /c 作为命令包装器：

{
  "command": "cmd",
  "args": ["/c", "npx", "mcp-remote", "http://127.0.0.1:8090/mcp"]
}

Connection works from CLI but not from Claude Desktop

原因： Claude Desktop继承了最小环境。变量如 PATH, HOME, PYTHONPATH，以及任何设置 .bashrc/.zshrc 是 不可用.

修复： 在中显式设置所有必需的环境变量 env 你的配置块。在所有地方都使用绝对路径——否 ~, $HOME或相对路径。

Silent config errors in Claude Desktop

原因： JSON语法错误 claude_desktop_config.json 静默失败--无错误对话框。

修复： 保存前验证JSON：

python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json

调试

MCP检查员

不使用客户端直接测试服务器 MCP检查员:

# stdio mode
npx @modelcontextprotocol/inspector python3 -m qdrant_mcp --transport stdio

# HTTP mode (start server first, then point inspector at it)
npx @modelcontextprotocol/inspector --url http://localhost:8090/mcp

Inspector提供了一个交互式UI来列出工具，用参数调用它们，并检查响应。

服务器日志

模式	位置
stdio	stderr（在终端或客户端日志中可见）
HTTP/Docker	`~/logs/qdrant-mcp.log` （可通过以下方式配置 `LOG_FILE` 在config.py中）
克劳德桌面	`~/Library/Logs/Claude/mcp-server-qdrant.log` （macOS）

安全注意事项

服务器以用户级权限运行。 运行服务器的用户可以访问的任何文件都可以通过以下方式读取 qdrant_ingest_file （在 ALLOWED_INGEST_PATHS).仔细配置路径白名单。
HTTP传输上没有身份验证。 端口8090上的可流式传输HTTP端点没有身份验证。如果您将其暴露在localhost之外，任何可以访问该端口的人都可以搜索、摄取和删除数据。绑定到 127.0.0.1 （更改 MCP_HTTP_HOST 在config.py中），如果你不需要局域网访问，或者使用带有身份验证的反向代理。
环境变量中的API键。 EMBED_API_KEY 是从环境或config.py读取的。避免将API密钥提交到config.py-使用环境变量或 .env 文件（已在 .gitignore).
Qdrant访问。 默认情况下，服务器连接到Qdrant时不进行身份验证。如果您的Qdrant实例包含敏感数据，请启用 Qdrant API密钥验证.

已知限制

大量摄入时无需流式传输。 摄入一个大的PDF（数百页）块，直到完成。服务器对其他工具调用保持响应（异步），但调用客户端将等待。
没有OCR。 没有文本层的扫描PDF提取为空。使用OCR工具进行预处理（例如。， ocrmypdf)在摄入之前。
不 .docx / .xlsx 支持。 先转换为PDF或文本。通过添加支持 python-docx / openpyxl 如果需要，它很简单。
块大小是基于单词的，而不是基于标记的。 分块器在空格上进行分割，这与模型标记化近似但并不完全匹配。这足以进行检索，但对于代币预算来说并不准确。
每个服务器实例有一个嵌入模型。 所有集合都使用相同的嵌入模型/维度。要为不同的集合使用不同的模型，请使用不同的配置运行单独的服务器实例。

贡献

这最初是一个个人基础设施项目，并作为参考实现共享。欢迎分叉和改编。如果你在上面构建了一些有趣的东西，可以随时打开一个问题来分享。

许可证

麻省理工学院

使用说明

Qdrant MCP Server

用法示例

搜索文档

摄入文件

摄取原始文本

浏览收藏

删除文档

使用文档

在哪里放置文件

支持的文件格式

更好检索的提示

工具

建筑

先决条件

必需

系统要求

快速启动

1.克隆并安装

2.配置您的嵌入提供程序

3.运行服务器

4.连接客户端

嵌入提供商

本地供应商

云提供商

客户端配置

克劳德桌面（stdio）

克劳德代码/VS代码扩展（stdio）

第.ai条（HTTP）

OpenClaw/Claude代码分叉（通过mcp-remote实现HTTP）

任何兼容OpenAI的客户端

配置参考

嵌入

Qdrant

服务器

安全

码头工人

数据持久化

在Docker中嵌入提供者

平台说明

使用现有的Qdrant实例

Docker镜像详细信息

项目结构

捆绑模块： rag/lib/

日志记录

错误处理

故障排除

调试

MCP检查员

服务器日志

安全注意事项

已知限制

贡献

许可证

相关 MCP

PowerPoint操作服务器

AI持久记忆服务器

Markdown转换服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议

捆绑模块： `rag/lib/`